Copyright (c) 1997 by the University of Washington. All rights reserved. This is a proprietary and confidential document. Under no circumstances may this document be used, modified, copied, distributed, or sold without the express written permission of the copyright holder.

The Visual Etch User's Guide

Contents

1. Introduction to Visual Etch

2. Running Visual Etch

3. Dynamically-Loaded Libraries (DLLs)
4. Etch Tools






1. Introduction to Visual Etch

Visual Etch is a graphical user interface to the Etch binary rewriting system. It is the standard way for users to interact with Etch and perform experiments to instrument or optimize x86 binary executables. This document describes the Visual Etch interface and the general environment that Visual Etch creates and manipulates in order to simplify the running of experiments.

In this document, we use "Visual Etch" to mean the graphical user interface and its environment; we use "Etch" to mean the binary rewriting program that Visual Etch invokes to instrument or optimize programs. The Etch rewriting program can be run without the Visual Etch interface; details of how to do this are contained in the Etching Applications from the Command Line document.

Visual Etch supports four generic functions:

  1. It provides a simple way for the user to define an Etch experiment that he or she wishes to run. The graphical user interface allows the user to easily select the application and the tool desired, and to define the parameters for the experiment.

  2. It manages files for the experiment, locating the modules to be processed by Etch (the inputs) and directing the writing of intermediate and final result files (the outputs). Visual Etch supports a project-based directory structure, allowing the user to keep separate outputs from different experiments. As well, Visual Etch maintains files used to improve the performance of Etch experiments (e.g., Visual Etch caches etched modules for possible reuse in later experiments).

  3. It directs the experiment, displaying to the user the status of the experiment, as various modules are processed by Etch to produce the modified executable. An experiment window shows the progression of steps as they are executed, as well as diagnostic output from Etch and other support tools.

  4. It initiates postprocessing of data outputs for the tool, displaying that data where appropriate in graphical form.
Like the Etch rewriting engine, Visual Etch is designed to be flexible and extensible; in particular, it supports the addition of new tools. The Visual Etch programming interface to tools and the process of adding new tools to the Visual Etch user interface are described in detail in the Visual Etch API document.

The process of "etching" an application and its DLLs is a complex one, in part because of the task of discovering code in the various binaries, and in part because of the general NT execution environment. Etch is designed to make instrumenting executables straightforward; however, some applications cause particular problems that must be dealt with by the user. See the Etch FAQ for a series of steps that will aid you in analyzing and dealing with problems that arise while using Etch.

2. Running Visual Etch

This section describes the Visual Etch interface used to run Etch experiments.

2.1 How To Start Visual Etch

You can start Visual Etch either using the File Explorer or through a command window. Through the File Explorer, go to the Etch distribution directory, open the bin folder, and double click on vetch.exe to execute Visual Etch. Through a command window, cd to the bin directory and type "vetch".

2.2 Choosing a Project

Visual Etch uses projects as its primary abstraction for organizing the work that a user does. A project is a directory used to hold a variety of state about an experiment or set of experiments using Etch. The following information is stored in a project: (1) the executable name of the last etched object, (2) all the DLL modules referenced by the executable, (3) a set of flags associated with each DLL indicating how it should be etched, and (4) a cache of etched objects (.exe and DLL files). When you start up Visual Etch, it creates a default project area for you to work in. The default project directory is named DefaultProject.vpr-DIR, and is created in folder %USERNAME%.temp within the temporary directory set by the environment variable %TMP%. For example, if your temporary directory is "Temp" and your username is "Fred," Visual Etch creates the project directory \Temp\Fred.temp\DefaultProject.vpr-DIR. Along with the DefaultProject.vpr-DIR folder in the %USERNAME%.temp folder, Visual Etch creates a file, DefaultProject.vpr, containing parameters describing the project.

While the default project is sufficient for running most experiments, you may wish to create different project directories to help manage and organize your experiments. You can use the "Project" menu in the main Visual Etch window to select or create a different project folder. If you start Visual Etch from the command line, you can specify a different default project directory on the command line (e.g. "vetch d:\myproject").

Projects are an organizational abstraction implemented entirely by the Visual Etch front-end; therefore, if you run the Etch rewriting engine -- rather than Visual Etch -- directly from the command line, Etch will not create this project structure.

2.3 Choosing an Application

After you've set the project directory, the next step is to choose an application that you want to re-write with Etch. First, click on the "Application..." button in the upper-left corner of the Visual Etch window. A file dialog box will appear, and you can navigate through the file system to select the executable you wish to etch. Select the executable using the "Open" button or doubleclick on the executable.

2.4 Choosing a Tool

The window labeled "Action" that is part of the top-level Visual Etch window contains a list of the available tools. Clicking on a label in the Action window gives a one-line description of the selected tool at the bottom left of the main Visual Etch window. Once you've decided which tool you want to use and you've set the appropriate settings using the "Application..." button, you are ready to invoke the selected action on the application and modules that you've chosen, i.e., to run the Etch experiment. For applications using dynamically-loaded libraries (DLLs), you will typically need to invoke the DLLwatch tool on the program before any other action; DLLwatch determines the set of dynamically-loaded libraries that are used by the application and adds them to the list of modules to be processed by Etch. This is described in detail in Section 2.2 and Section 2.3; or, see the example experiment walk-through in Section 2.8.

2.5 Executing an Action

Once you've selected an application and tool, you run the experiment by clicking on "Execute Action." When you click "Execute Action," a window "Visual Etch: Running Experiment" appears. The information panel at the top of the window describes the application and experiment, and the progress bar tells (loosely) how much of the experiment is done. Within the window are three subwindows that give status information about the Etch experiment being performed. At the top, the Check List window gives you an overview of the steps needed to perform the experiment; this usually includes one or more runs of Etch on the application executable and DLLs, running of the etched application executable, and postprocessing of the data output produced by the tool, if any. Each step is highlighted as it is carried out. The middle window, titled "Run Details," gives more precise messages about the progress of the various steps being executed. The bottom "Problems" window gives a summary of problems, if any, that occurred while the experiment was running.

Under the "Status Windows" menu at the top of the Running Experiment window, you can choose two options: console window or debug window. These windows are selectable as well through the "Options" menu in the main Visual Etch control window, from which you selected the application and tool. The debug window is used by the UI for debugging purposes, so it may not be of interest to you. The console window provides a record of commands executed and tool output produced during execution.

When you click on "Execute Action", Visual Etch runs the etched application as the last step of its checklist, as shown in the Check List subwindow of the Running Experiment window. In addition to the Execute Action button in the main Visual Etch window, there are two additional options as indicated by the two adjacent buttons:

2.6 Examining the Results of Experiments

The final step in the checklist for each tool is typically a postprocessing of the output produced by the tool. When this step is initiated, Visual Etch displays the output produced. For viewing output results, Visual Etch supports tables, graphs, and text output windows. Most experiments produce a file called "tool.output" in the experiment folder of the cache directory; here "tool" is the name of the tool you invoked, e.g., "ophisto.output" for the histogram tool, or "countiref.output" for the instruction count tool. (Selecting "Options|Command Prompt|In Experiment Folder" in the control window will give you a command window set to the experiment folder.) The experiment scripts also produce a log that describes how the program modules were etched and any errors or warnings that occurred while etching. This log is stored in the file etch.log in the experiment folder. You can see this log by selecting "Show Log File for Selected Tool" in the "Previous Runs" menu in the Visual Etch control window.

When you re-run a specific experiment (a particular tool on a particular executable, using a particular project directory), Etch replaces the .output and .log files from previous runs of that experiment. These files are also erased from the experiment folder if you select "Options|Clear Cache" from the UI.

Visual Etch also allows you to save the log and output files of previous runs to a different directory for later use. In the Visual Etch control window, use the "Previous Runs" menu and select "View/Copy Output and Log Files for Selected Tool." Select a .log or .output file of interest in the Source Files list by clicking on that file name; double click on the file (or click the View button) to view it, or move it to the selected Destination Directory by clicking on "Copy As".

2.7 Files Used and Created by Visual Etch

As noted above, Visual Etch creates a default project directory (DefaultProject.vpr-DIR) in the temp directory. Users can create new project directories in other locations by using the "Open Project" menu item.

In the project folder, Visual Etch creates a structure of files and folders, which includes (among other things) the following:

2.8 Walk-through of an Etch Experiment

In this section we walk through an experiment using Visual Etch to give you the experience of the process you will typically go through when instrumenting applications. Let's assume that you wish to make some simple measurements of the application calc.exe, a visual desk calculator. In particular, assume that you wish to do an opcode histogram of the application as it is used. The steps below show how to perform this experiment.
  1. Start Visual Etch. Using the File Explorer, go to the Etch distribution folder. Double click on the bin directory to open it. Scroll to the bottom, find vetch.exe, which is the Visual Etch interface, and double click on vetch.exe to start it. You're now running Etch through the Visual Etch interface.

  2. Create a Project. Now create a new project folder in which to keep all the files associated with our experiment. Go to the "Project" menu at the top of the Visual Etch window, and select "Open Project." Using the file finder at the top of the Open Project window, locate the drive and folder in which you would like to store all of your experiment files. Let's call our experiment EXPR1, so enter "EXPR1" in the "file name" box at the bottom. Click "Open". Visual Etch will create a folder called EXPR1.vpr-DIR as your top level project folder. Inside of EXPR1.vpr-DIR, Visual Etch has created a cache folder in which to store the experiment files. Now close the "Open Project" window. Notice that the Visual Etch window indicates EXPR1.vpr, your project, at the top.

  3. Select an Application. Select the application to instrument. In the main Visual Etch window, click "Application" to bring up the "Select Executable" window. Using the file finder, locate the .exe file you wish. In this example, you're looking for calc.exe, and when you find it, double click on calc.exe to select it. The Visual Etch window now shows calc.exe as the application.

  4. Run DLLwatch. Before choosing any measurement or optimization tools, run DLLwatch on the application to be sure that you include all DLLs that will be used by calc.exe. Click on DLLwatch in the Action window to select that tool. Now click the Execute Action button below to run DLLwatch on our application, calc.exe. You will see the Visual Etch "Running Experiment" window, as Visual Etch processes calc.exe with the DLLwatch tool and then runs the processed executable. In this case, calc.exe is an interactive application, so use the application in the same way that you will use it for the measurements. Then exit the application. Visual Etch will display the results of the DLLwatch tool -- a list of all the DLLs it found -- and will ask whether you wish to include those DLLs in the list of modules to be etched.

    • If you click on the "Modules" button in the main Visual Etch window, you will now see a list of the modules that will be processed by Etch during our experiments, including the application executable, calc.exe, and the DLLs that it uses.

    • If you look in the File Explorer again, you will see a new experiment folder, called calc.exe-dllwatch, inside of the cache folder of your project (i.e., the path is \EXPR1.vpr-DIR\cache\calc.exe-dllwatch). This experiment folder contains information about the first experiment we ran -- the application of DLLwatch to calc.exe -- and contains parameter settings and the tool output.

  5. Run a Measurement Tool. Now select a measurement tool to run. In the Action window, click on Opcode Histogram, which you wish to run. Click on Execute Action to apply the Opcode Histogram tool to calc.exe. Once again we see the "Running Experiment" window, showing us the steps guided by Visual Etch to process all of the modules. Once the processing steps are finished, Visual Etch runs the modified executable. Again, use calc.exe in whatever way you wish for the experiment. When you exit the application, Visual Etch brings up the results window; for this experiment, you can view the opcode histogram results as a list or a graph.

Note that DLLwatch needs to be run only once for this set of experiments. If we wish to run other tools on the same executable using the same project file, we do not need to re-run DLLwatch.

2.9 The Visual Etch Cache

To facilitate running an etched binary multiple times, Visual Etch implements a caching mechanism; that is, previously-etched binaries are cached in files stored in the experiment folders (e.g., Project.vpr-DIR\cache\ApplName.exe-tool for the default project).

Visual Etch uses a number of checks to ensure that cached versions of etched modules are up to date. First, it compares the modification time of the cached modules with the modification time of the source binaries, to ensure that the cached modules are newer than source binaries. Second, it checks to make sure that the cached binaries were produced with the same arguments to Etch as required by the new command.

In the Visual Etch control panel, you can select the "Options|Clear Cache|All" menu item if you wish to delete cached versions of etched modules in the current project, either to save disk space, or to guarantee that the entire application is freshly etched. You should not clear the cache while an Etch experiment is in progress.

2.10 Running Applications with Scripts and Command-Line Arguments

Some applications need to be invoked with special command-line arguments or in a specific environment. To support this, Visual Etch allows the user to specify a script that should be used to run the etched application; as well, the user can specify command-line arguments that should be passed to the application or to the script.

Specifying command-line arguments is straightforward: the user can simply type them into the "Application Command Line Options" line in the main Visual Etch Window.

To specify that Visual Etch should not run the application directly, but instead should use a user-provided script, you should check the "Use Script to Drive Application" box. You can then use the "Script..." button in the Visual Etch command window to browse the file system for the script. If command-line arguments are specified and the "Use Script.." box is checked, the arguments are passed to the script.

Writing a Script

Consider a script whose task is to run the program foo.exe. The script is responsible for setting up the environment needed by foo.exe to run properly (generating input files, setting the path, etc.) and to invoke the newly-etched version of foo.exe (rather than the original program).

The name of the etched application is communicated from Visual Etch to the script via the "NEWEXENAME" environment variable. In some cases "NEWEXENAME" will include the name of an auxiliary program such as DLLwatch that must be invoked to run the application. Thus, typical values for "NEWEXENAME" when instrumenting the program "foo.exe" would be "foo-etch.exe" or "dllwatch foo.exe".

In summary, a trivial perl script -- a script that simply invokes the etched program without performing any additional tasks -- would be:

#!/usr/local/bin/perl
system("$NEWEXENAME");

Special Cases: Perl and Microsoft Test

Visual Etch provides special support for two common cases, perl scripts and Microsoft Test scripts. If the script has the extension ".pl", Visual Etch invokes the script via perl; if the script has the extension ".mst", Visual Etch invokes the script via Microsoft Test.

2.11 Computer Parameters for Cache Simulation

The "Options" menu in the Visual Etch UI contains a menu item called "computer parameters." Selecting this item brings up a form in which you can define processor configuration parameters, including processor speed, cache size and associativity, TLB size and associativity, etc. You can easily initialize the values for those for various standard platforms by selecting one of those platforms from the top menu item, or else enter or modify parameters individually. The values entered do not necessarily represent the hardware on which Etch is executing; the purpose of this menu is simply to provide an interface for Etch users to define hardware parameters for tools performing hardware (e.g., cache or TLB) simulation. Visual Etch passes these parameters to the simulation tools in the project.txt file in the project directory; Visual Etch also places a copy of project.txt in the experiment directory for use as diagnostic information. Otherwise, neither Visual Etch nor Etch uses this information directly.

2.12 Selective Etching of Procedures

If debug information is available in any modules, Visual Etch allows you to selectively choose the specific procedures to be etched in those modules. In the main Visual Etch window, choose "Options|Selective Etching" to open the selective etching control window. Within that window, check "Use Selective Etching" to enable selective etching of procedures. The list shows the procedures identified; Etch will process procedures with a "+" in front of their names and will not process procedures with a "-" in front of their names.

2.13 Rebasing Etched Modules

Loading an application is often slow, because the loader must relocate all of the modules so that they occupy unique address ranges. The Visual Etch option "Options|Rebase Etched Modules" performs this function ahead of time, so that loading occurs more rapidly. This is useful if an etched executable and its associated modules will be run multiple times. If the etched executable will not be run multiple times, it is probably not worth the overhead of relocating the modules in advance. (This function requires editbin.exe to be in the path.)

3. Dynamically Loaded Libraries (DLLs)

An important job of Visual Etch is to identify the set of DLLs used by an application, rewrite them, and arrange that the new versions of the DLLs are used by the rewritten version of the application. This section gives a brief introduction to DLLs on NT and Win95 and then describes the strategy used by Etch for dealing with DLLs correctly.

3.1 DLLs on NT

The DLLs used by a given NT application can be divided into two categories: "implicitly-loaded" DLLs and "explicitly-loaded" DLLs. Sometimes these are called "statically" and "dynamically" loaded DLLs. Implicitly-loaded DLLs are loaded automatically during process initialization, because they are referenced in the executable's import table. Explicitly-loaded DLLs are loaded by the application after process initialization through the Win32 LoadLibrary call.

3.2 DLLwatch

To instrument a program correctly, Etch needs to know about all the dynamically-loaded libraries used by the application. This is necessary for two reasons: to capture additional activity caused by the application, and to prevent NT from loading both the instrumented and the original DLL at the same time. The implicitly-loaded DLLs are discovered by a recursive scan of the import table, however, discovering explicitly-loaded DLLs is more difficult. Etch therefore provides a tool, "DLLwatch", to help you identify the set of explicitly-loaded DLLs used by the application. If you know the entire set of DLLs then you can enter them directly using the Modules dialog window (described below).

The DLLwatch tool monitors and summarizes calls to LoadLibrary and other routines that load or manipulate DLLs. DLLwatch imposes negligible overhead. You should first run the application using the DLLwatch tool in exactly the environment you will use for your experiments, in order to ensure that the full set of explicitly-loaded DLLs are discovered.

After you run DLLwatch, DLLwatch automatically adds the DLLs it found to the Modules list.

In general all of the DLLs will be identified by DLLwatch, but it is still possible that some DLLs will not be found. In particular, if the DLLs to be loaded are data or input specific, and the application is later run with different data or input, then DLLwatch may not catch those DLLs. See Section 3.4 for more information on this problem.

3.3 The Modules Window

To facilitate control of which modules are etched and how they are etched, Visual Etch provides the Modules window. To see the Modules window, click on the "Modules..." button in the main Visual Etch window. The Modules window shows one line for the target executable and one line for each of the DLLs known to Visual Etch. Initially, this list includes only the set of implicitly-loaded DLLs (these were discovered by Etch automatically when you selected the application). The "options" menu in the Modules window provides entries to add and remove explicitly-loaded DLLs from the list. You can add explicitly-loaded DLLs one at a time by browsing the file system. However, typically you will add them en masse by running DLLwatch, which automatically adds the DLLs it finds, when you respond positively to its dialog box following the experiment. DLLs whose names are shown in upper case letters are explicitly-loaded DLLs, while those shown in lower case are implicitly-loaded DLLs. A "*" preceding the name of a DLL indicates a DLL that is not normally etched.

For each module shown by the Modules window, the interface allows the user to set the parameters used to etch the module. Typically these parameters can be left at the default settings. (The default settings are stored in tables in the MS Access file etch\bin\params.mdb: global defaults live in the table "Etch", while per-module defaults live in the table "Module EtchFlags".) If you wish to change the parameter settings, the following options are available:

Etch - This controls whether the transformation specified in the "Action" menu is applied to the given module (i.e., whether to etch the module with the given tool). This option is on by default except for DLLs that can fail when instrumented. These DLLs are noted with an asterisk; clicking on the DLL will cause a brief description of the problem with the DLL to appear at the bottom of the window. Some more information is provided in "DLL Limitations" (Subsection 3.5) below.

Patch - This option indicates that whether or not a module is etched, its import table should be updated to import etched DLLs rather than the original DLLs. As with the Etch option, this option is on by default except for DLLs that are known to fail, even if simply patched. This option should only be used if it is necessary to instruct Etch to ignore the presence of the particular module for the etched application to run correctly.

Aggressive Code Discovery - On by default, this option controls the aggressiveness of the rules that Etch uses to distinguish code from data. In general, we have found that misidentification of data as code is rare, so it is not necessary to use this option.

Fast Context Save - Off by default, turning on this option indicates that the context save code surrounding procedure calls from the etched application to the tool runtime DLL does not need to preserve data above the top of the stack. A small number of DLLs keep live data above the top of the stack: the default "slow context save" code path preserves this data on entry and exit to the tool runtime code. For DLLs that have been determined not to have this deprecated behavior, it is possible to speed up experiments somewhat by choosing fast context save. (You can use the "Check Data References" tool to monitor runtime stack references and determine whether an application has this stack problem.) FastContextSave can also reduce disk space and memory usage.

Save Floating Point State - Off by default, this option controls whether floating point is saved and restored on calls into the tool runtime. Specifying this option will add considerable overhead to these calls, and is only necessary when both the tool and the DLL being transformed use floating-point operations.

Use Original Image Base - Off by default except for USER32.DLL, this option indicates that the etched or patched image file should be linked at the same image base as the input image. The default behavior is for Etch to choose a new image base automatically. Currently all etched and patched DLLs are simply linked to a single image base. This strategy prevents etched DLLs from being linked at addresses that conflict with the addresses of some system DLLs. USER32.DLL is handled differently, because the kernel effectively has hardwired entry points into this DLL that assume that the image base is fixed. So far we have not identified any other DLLs with this behavior.

Use Original Module Name - Off by default, this option indicates that the etched module should be given the same name as the original module. Normally the etched or patched version of a module with the name "application.exe" would be named "application-etch.exe" or "application-patch.exe", respectively. This option is needed for programs that look for data files based on the application name, and will not find the files if the application name changes. It is strongly recommended that this option not be enabled for etched or patched DLLs, because it can lead to unetched applications using the modified DLLs, or the etched application using the unmodified DLLs.

3.4 What Can Go Wrong

If the full set of DLLs used by an application is not specified at Etch time, it is possible that the etched application will try to load unetched or unpatched versions of DLLs as it runs. This could result in both an original and transformed version of a DLL being mapped into the process address space, leading to unpredictable behavior.

An Etch runtime library (etchwrap.dll) intercepts calls to LoadLibrary and GetModuleHandle and redirects references to the transformed version. If etchwrap.dll detects a reference to a module that was not Etched, it pops up a dialog box and asks the user how to proceed. The safest course is to terminate the application. A slightly less conservative approach is to return a failure code to the caller and hope for the best. Finally, the user can choose to load the original library, although this may result in unetched versions of various system DLLs being mapped. When unetched or unpatched modules are identified, the runtime sytem writes entries in the file etchwrap-orphans.log identifying those modules, so that the modules can be etched or patched in future runs.

3.5 Current DLL Limitations and Special Cases

The primary DLLs that are by default not etched in the current implementation are NTDLL.DLL, KERNEL32.DLL, and USER32.DLL. NTDLL.DLL and KERNEL32.DLL are not modified at all, while USER32.DLL is patched but not etched. Code in these DLLs is not instrumented and therefore not measured. (Note: It appears that etching KERNEL32.DLL will work, but we have not done enough testing to warrant enabling by default.)

4. Etch Tools

Etch tools direct the rewriting, for instrumentation or optimization, of application binaries. Etch is designed and structured to make it simple to write and use such tools. As part of the Etch distribution, we provide a set of standard tools that can be used for measurement and optimization. These tools are briefly described below and are listed in the "Action" window of the main Visual Etch interface window.

The tools fall into several categories.

  • Etch Support Tools -- Tools that you use to help Etch do its job. This currently includes only DLLwatch for identifying DLLs used by the application.

  • Stable Tools -- These tools have been around for a while and we feel confident in their operation.

  • Optimization Tools -- These tools are used to optimize program performance.

  • Tools That Require Debug Information -- These tools require debug information in order to work properly.

  • Cutting Edge Tools -- New tools or tools that are known to have bad interactions with other programs.

  • Etch Debug Tools -- Tools that you can use to help in the etching of programs or writing of new tools. The tools are described in more detail below.

    4.1 Etch support tools

    DLLwatch
    Generates a list of DLLs used by the application and adds those DLLs to the modules to be instrumented, as shown by the Modules window.

    4.2 Stable tools

    Cache Miss Distribution
    Simulates a memory system with two-level cache. The simulator consists of separate first-level instruction and data caches (virtually indexed) with a unified second-level write-back cache (virtually or physically indexed). Cache size, associativity, and write policy are configurable. If debugging information is available, the information on misses will be attributed to individual procedures.

    Data References
    Counts the number of dynamic loads and stores executed by the application.

    Instruction Counts
    Counts the number of dynamically-executed instructions using per-instruction instrumentation.

    Opcode Histogram
    Generates a histogram of opcodes executed by the program, displayed by instruction mnemonic.

    Thread Safe Instruction Counts
    Counts the number of dynamically-executed instructions, as in the instruction count tool above, however uses locks around the instrumentation data and is therefore usable by multithreaded programs.

    Unaligned Accesses
    Counts the number of unaligned data references. The output contains the total number of loads/stores and the number of unaligned loads/stores.

    4.3 Optimization Tools

    Profile for code layout
    Profile instruction references to improve code layout.

    Optimize for code layout
    Using the output of the profiling step, reorder instructions to reduce cache pressure.

    Measure optimized performance
    Compare the cache behavior of an optimized and unoptimized program.

    4.4 Tools That Require Debug Information

    Malloc and Free Usage
    Monitors dynamic memory allocation usage calls to malloc, free, and realloc. This tool records the number of calls made, the total bytes allocated, the total bytes freed, and the peak memory usage. For each block of memory that was leaked, it prints out the call site address. This tool requires debugging information to locate the calls to malloc, free, and realloc. It also requires that those calls implement the standard ANSI C interface (w.r.t. location of arguments on the stack).

    4.5 Cutting Edge Tools

    Cache Animation
    Provides a graphical animation of the cache simulator. Only the first-level caches are displayed. Shown on screen are two regions representing the instruction cache (left) and data cache (right). For each cache access, the simulator highlights the row representing the cache line in which the access occurred. A "tick" noise is generated if the access was a cache miss. The "Stop" and "Start" buttons can be used to suspend and resume animation; simulation continues (at a faster rate) when animation is stopped. The final output is the same as the regular cache simulator.

    Call Graph Profiler - cycle counts
    Generates a call graph, listing caller-callee pairs and the number of invocations. Reports time spent in procedures based on the hardware cycle counter.

    Call Graph Profiler - instruction counts
    Generates a flat call graph, listing caller-callee pairs and the number of invocations. Reports time spent in procedures based on instruction counting.

    DLL Call Tracer
    Logs the source and target of every DLL call. This only works for calls that are made through the import table (because the tool only instruments DLLs that are known at instrumentation time).

    Hardware Performance Counters
    Sets and starts the selected Pentium or PentiumPro hardware counters to be used to measure the application. The tool prints the counter values that were measured during the experiment.

    Instruction Counts Using Basic Blocks
    Counts the number of dynamically-executed instructions using basic block instrumentation. This tool illustrates the speedup of basic block over per-instruction instrumentation (when compared with the standard Instruction Count tool).

    Trace INT Instructions
    This tool maintains a log of int (software interrupt) calls made by an executable to perform system calls.

    4.6 Etch Debug Tools

    Check Data References
    Checks to see if illegal references are made by the instrumented application: e.g., references to instrumented text sections or data above the stack. The application should not know about the instrumented text section, therefore references to it indicate an error. Since we insert calls between instructions, we have to know whether or not to save values above the stack. The default is to save 48 bytes above the stack. If no references to above the stack pointer are detected, "fast context save" can be used to reduce per-instruction instrumentation runtime overhead. Likewise, if there is a reference higher than our saved area (> 48B), this tool will stop the application and report the offending PC in the application. In this case, the save area needs to be increased (this can be done by a command-line argument to Etch -- see the Etch Command Line Interface) documentation.

    DLL Instruction Counts
    This tool counts the number of instructions executed, broken down on a per-DLL basis. It also attempts to estimate the number of instructions executed in un-instrumented DLLs. The technique used for estimation will not work on multi-threaded applications. This tool runs only on a PentiumPro.
    Dll Test
    Rewrites the application, but does not perform code modification. There is no interpretation of the executable (i.e., no code discovery). There is no output. This tool is useful for isolating problems with instrumentation from problems with DLL management: the DLL Test exercises DLL management only, without modifying the code or data of the application except for the import tables.

    Insert Nops
    Inserts a NOP before each instruction. There is no output.

    Instrumentation Coverage (Approximate - fast)
    This tool calculates the dynamic instruction count coverage. It increments a counter for each instruction instrumented, and also counts the number of total instructions executed by the instrumented program. Given the per-instruction instrumentation overhead (in instructions), it estimates what the dynamic instruction count would have been in the uninstrumented program. The output contains the total count in the instrumented program, the number of instrumented instructions, and the estimated instruction count in an uninstrumented program. Estimations may be overly high, or overly low for short-running programs.

    Instrumentation Coverage (Exact)
    This tool determines dynamic instruction count coverage exactly. It counts all instructions executed by the application, and counts how many of those instructions executed were discovered by Etch and how many were not. Counting executed instructions that were not discovered by Etch relies upon a very slow mechanism in order to perform precise counts.

    Instrumentation Coverage (Exact - etched)
    This tool determines exact dynamic instruction count coverage for the etched modules of an application. It dynamically counts all of the instructions discovered by Etch, as well as the instructions missed by Etch that are in the modules processed by Etch. In other words, this tool does not count instructions executed in modules not processed by Etch.

    Null Instrumentation
    Rewrites the application, inserting no instrumentation before each instruction. In this case, the program bytes are interpreted (i.e., code discovery is exercised). There is no output.

    Run Original
    Executes the original unmodified application.

    Validate Procedure and Basic Block Boundaries
    Code discovery sanity check tool. Uses instrumentation information and runtime information to count instruction, basic block, and procedure entry/exit points. These counts are performed in numerous independent ways to validate the various instrumentation points.