1. Introduction
This document describes the interface between the Visual
Etch user interface and Etch instrumentation tools.
In particular, it shows how to integrate a new tool into
the Visual Etch environment, and what procedural and
environmental support facilities Visual Etch provides for tools.
This document is intended only for tool writers wishing to add
their tool to the Visual Etch user interface. It does not
describe the end-user interface to Visual Etch; that is
described in detail the Visual Etch User's Guide.
There are actually three components that participate to execute an
Etch experiment through Visual Etch. These components commmunicate
through various interfaces described in this document. The
communication is through files, global variables, or procedure calls,
depending on the components communicating. The three major components
responsible for running an experiment through Visual Etch are:
1.1 Overview of Visual Etch Components and Interfaces
Visual Etch presents the user with a window- and menu-based
environment for controlling instrumentation and optimization
experiments on executables. It allows the user to specify the
executable and DLLs of interest, together with the script or command
line parameters that should be used to run the executable. The user
also specifies the tool that they wish to apply to the executable.
This document describes the steps for integrating tools
into Visual Etch and the associated tool scripts used by
Visual Etch. To integrate a tool into the
user interface, the tool implementor must understand
five main interfaces:
1.2 An Example of Adding a New Tool to Visual Etch
In this section, we briefly walk through the steps of integrating a new tool
into the Visual Etch user interface. For this example, we integrate
an unaligned access counting tool, as described in the
Etch Tool Writer's guide. In the sections
following this example, we describe in more detail the various interfaces
and the Visual Etch environment in which tools and scripts execute.
The steps for adding a new tool to Visual Etch are as follows:
For the unaligned access counting tool, create unaligned-inst.cxx and unaligned-rt.c using Visual C++. Compile these two files into unaligned-inst.dll and unaligned-rt.dll.
Copy unaligned-inst.dll and unaligned-rt.dll into etch\apps\bin.
We're going to call this tool "unaligned", so create a perl file called
unaligned.pl in the etch\bin\scripts subdirectory, with a perl function
called unaligned. Following is an example of the unaligned perl function.
While the details of the calls are described later in this document,
the comments in the function indicate the basic steps that it is performing. This
code can be used as a template for other tools.
Notice that among other things, this perl script invokes Etch,
manually adjusts the progress bar displayed in the Visual Etch "Running Experiment"
window at various points, and invokes a function to visually display the tool output.
For details on other perl functions that the tool scripts can call, see
Section 3.
Visual Etch automatically looks scripts to run a tool in the directory
etch\apps\bin\scripts. All files that end with the suffix
.pl in the directory are searched for one that contains the
subroutine called with the same name as the tool, in this case
sub unaligned.
When Visual Etch starts up, it reads all the files with the suffix
.desc in the etch\apps\desc subdirectory. These
files describe what should be contained in the "Action" list in the
Visual Etch window. In this case you will create a file called
unaligned.desc:
< tool>-toolinfo.txt is a text file describing for the user
the output of the tool and, if necessary, how the output should be interpreted.
In this case, Visual Etch looks for unaligned-toolinfo.txt to display
together with the tool output.
Visual Etch needs to be restarted for the changes to the tool list
to be reflected. Quit all instances of Visual
Etch and then start Visual Etch again. Visual Etch should now show your tool in the tools
list. If it does not, check to ensure that no other instances of Visual Etch are still running.
sub unaligned {
local($debugfile) = "";
# Create checklist to tell user what's happening
# Etch $EXENAME and associated DLLs -> we're etching the application
# Run $EXENAME -> Run the etched application
&mCheckList("Etch $EXENAME and associated DLL's,Run $EXENAME");
# Determine if the user wanted to etch the application
# ("Execute Action" or "Etch Only")
if (ACTION_SHOULD_ETCH()) {
# Yes. The user wanted to etch the application
# Clear the working directory of etched application and state
# from previous runs
SetupWorkingDir();
# Etch the application, passing application name, tool name,
# and list of DLLs to be etched
&etch($EXENAME,"unaligned","","","",@ModuleNames);
}
# Check off "Etch EXENAME and associated DLL's"
mCheck(0);
# Increase the progress bar. We're 50% done
mProgress(50);
# Find the name of the processed application. It's either
# app-etch.exe or app-patch.exe.
$outname = FindProcessedExecutable($EXENAME);
# Determine if the user wanted to run the application
# ("Execute Action" or "Run Only")
if (ACTION_SHOULD_RUN()) {
# Run the etched binary.
&run($outname);
# Show the result in a table format
mTable("Unaligned Accesses","$WORKINGDIR\\unaligned.output");
}
# Check off "Run EXENAME"
mCheck(1);
# We're 100% finished
mProgress(100);
}
# need to put a 1 at the end of a script file because the perl
# require mechanism requires this.
1;
#
# This is the description file for the unaligned tool
# All the fields defined in this file must be present for
# all tools in desc files.
#
# One desc file may contain descriptions for multiple tools
# as long as they are delimited by the index field
#
# Index delimits different tools. This indicates that
# a new tool is will be described
#
# Index also tells where you want the tool to appear in the tool list.
# Since the tool is still experimental, we put in 3001 which causes it
# to be clumped with "Cutting Edge Tools" in the tool list.
Index = 3001
# Metric - the string you wish Visual Etch to display to the user in
# the tool list
Metric = Unaligned Accesses
# ToolName - name of the tool
ToolName = unaligned
# User options - you can specify a table of tool-specific options that
# Visual Etch will request from the user.
# "null" in this case because the unaligned tool has no special options
UserOptions = null
# Help - A help text that Visual Etch will display in the status bar
# when the tool is highlighted.
Help = Count unaligned accesses
< field> = < value>
The required fields are:
Note: All options must have the same additional
fields and that each of the fields cannot be blank.
2.3 Telling Visual Etch to ask users for tool-specific options
When adding tools to Visual Etch, you can set up options for the
user to specify by creating a .params file in the
etch\apps\bin\params subdirectory. Visual
Etch will prompt the user to specify these options before running the
tool script. These options are read into the %PROJECT associative
array and accessed through:
$value = $PROJECT{[tool],[key]}
Each option in the .param file is required
to have at least six fields of the form:
For an example of how this works, look in the file CPU.params in the
directory etch\apps\bin\params.
< field> = < value>
The fields have the following data:
2.4 Information Visual Etch passes to the tools
Visual Etch passes along particular information that the user has
specified to an external user-specified routine. The user specifies
the routine and its inputs though dialog screens. Before Visual Etch
calls the routine, it sets up several environment variables as well as
several project files: project.txt, etchparams.txt,
and for each module a [application].options file. Details of
these files can be found in Appendix A
Although the tool scripts can parse
the information in these files and the environment variables,
coordinator.pl parses these files and environment variables
and puts them into perl global variables as a convenience for tool scripts.
The following global variables are defined in coordinator.pl and
can be used by the perl tool scripts. They are derived from the contents
of the file project.txt and from environment variables set
by Visual Etch.
For an example of how this works, look in cache.pl in the
%ETCHBIN%\scripts subdirectory.
The rows with tool name Project are values set by Visual Etch. These keys
are:
etchparams.txt contain the per module etching options that the
user specified through the Modules dialog box. This file
contains triples of the form [Module name, Etch parameter, value]. The Etch
parameters are:
For selective etching, Visual Etch creates an [Application].options
file that lists the procedures that are contained in the application
and whether or not these procedures should be etched. The file
contains triples of the form [option,module,procedure]. Module and
procedure gives the module name and procedure name respectively.
Option can be either "+" or "-"; "+" means etch the
procedure, "-" means do not etch the procedure.
2.4.1 Global Variables defined for perl scripts
Directories
Application Information
Project Information
Miscellaneous
Machine parameters
3. Visual Etch Services for Tool Scripts
This section describes the services that the tool scripts can use to
run Etch, run the executable, and show the results of the experiment.
3.1 Support subroutines for tool implementation
This section describes the predefined perl subroutines to help the tool
writer implement their tool. Although there are many routines that the
tool scripts can use, most tools will only need the following routines:
An example tool script is here
3.1.1 Subroutines to run Etch
These are routines that encapsulate the complexity of etching a full
application. Most tools will just need the etch subroutine described
below; some tools, however, may need behavior different than
that caused by the etch
subroutine, and these tools will need to call the individual subroutines that
the etch subroutine calls in a different way. These tools are defined in
scripts\etch.pl file.
3.1.2 Subroutines to run applications or scripts
These routines help with running the application or scripts. Most tools
will only need the run routine, but other tools may require
something different and would have to call the other routines in a way
different from run.
3.1.3 Auxiliary routines
Following are additional routines that Visual Etch defines to help with etching.
3.1.4 Callbacks to Visual Etch
Following are routines that are used for sending messages to Visual Etch.
These routines are defined in message.pl.
3.1.5 Utility functions
3.2 Caching Previously Etched Modules
The routines to help run Etch provided by
Visual Etch create a cache of previously etched modules under the
EtchedModules subdirectory to speed up subsequent runs of etch.
To keep this cache coherent three tests are performed:
IMPORTANT: Sometimes tools may have metadata that cannot be
captured in these three categories, but nevertheless affects how a
file is etched (e.g. a user parameter to determine which Procedure
to instrument). Under these circumstances, it is the tool writer's
responsibility to encode this information with a stamp that can become
a part of the Etch arguments (e.g., through the -stamp option).
3.3 Miscellaneous
Communication between scripts to run applications and Visual Etch scripts
Scripts to run the application should use the environment variable
NEWEXENAME to find the executable name of the executable to
be run. This environment variable is initialized by the run
subroutine before it executes the script.
Making tools ready for Visual Etch
The Visual Etch scripts usually expect that the output of the programs
are placed in %WORKINGDIR%. A utility for getting this name is in the
apps\libutil subdirectory etchOutputName. For an
example look in ProgramAfter in unaligned-rt.c. The tool runtime DLL should
also respect the ETCH_UNIQUE_OUTPUT environment variable
which tell it that each process should output to a unique file.
Appendix A. Visual Etch Interfaces
Most tools will be written in Perl and hence would only need to understand
the Perl global variables and routines that provided by Visual Etch.
However, tools written in other languages have to understand the interfaces
of how
Visual Etch passes information to the tools and
how Visual Etch shows user feedback.
A.1 Information Visual Etch passes to the tools
Visual Etch passes along particular information that the user has
specified to an external user-specified routine. The user specifies
the routine and its inputs though dialog screens. Before Visual Etch
calls the routine, it sets up several environment variables as well as
several project files: project.txt, etchparams.txt,
and for each module a [application].options file.
A.1.1 Visual Etch environment variables
A.1.2 Visual Etch project files
Before Visual Etch runs coordinator.pl and the tool script,
it creates several project files that contain the options that the user
specified through the UI. For boolean options, the option values are encoded as the
strings "Yes" and "No", e.g.: "winword.exe, SHOULDETCH, Yes".
A.2 Asking Visual Etch to show user feedback
Visual Etch communicates with the tool script through an anonymous
pipe and events. Visual Etch passes the handle for the write end of the
anonymous pipe in the environment variable PipeHandle, and it passes
the event names through the environment variables serverWait
and clientWait. To send a message to Visual Etch,
simply write a message to PipeHandle, signal the event serverWait,
and wait
for the event clientWait. Tool scripts that are not written in perl
need to send these messages explicitly; however, tools written in perl can use the perl
subroutines defined in message.pl.
Following is the list of messages that Visual Etch recognizes and
the action performed by Visual Etch on each message. A description of
these messages is given in Section 3.1.4.