SPIKE VERSION 1.4 RELEASE NOTES

Spike is a tool for optimizing Alpha/NT executables and DLL's.
If you have additional questions or suggestions about Spike, send
mail to spike@vssad.hlo.dec.com.


------------------------------------------------------------------------
CONTENTS
	1. INSTALLING SPIKE
	2. UNINSTALLING SPIKE
	3. USING SPIKE
	4. COMPILING FOR SPIKE
	5. UNSUPPORTED/SPECIAL-CASE APPLICATIONS
	6. USING THE SPIKE OPTIMIZER

------------------------------------------------------------------------

1. INSTALLING SPIKE

To install Spike, simply run setup.exe. Due to an NT limitation, the
length of the path where you install Spike can be at most 10
characters. Due to significant changes in this version, you
should first uninstall previous versions of Spike using the
spkclean.exe included in this kit, and then restart your computer
before running setup.


2. UNINSTALLING SPIKE

Do not use NT uninstaller (uninst.exe) to remove Spike; instead run
spkclean.exe to uninstall Spike.


3. USING SPIKE

Spike consists of the Spike Optimization Environment, and the Spike Optimizer.
The Spike Optimization Environment (SOE) provides a simple means to instrument 
and optimize applications. SOE maintains a database of applications and 
images (exes and dlls) as well as any profile information collected for those 
images, allowing the user to easily optimize large applications containing
multiple dlls. SOE can be accessed using either a gui interface (the Spike manager)
or a command-line interface (spkcmd.exe). Additional on-line help is available
through the Spike manager (invoked from the Start menu or by running spkmngr.exe
in a command prompt).

The Spike Optimizer can be accessed through a command-line interface to
instrument or optimize a single image. Additional information on using the
Spike Optimizer is available in the online-help, and at the end of this file.


4. COMPILING FOR SPIKE

To optimize an image, Spike prefers that the image be compiled with VC5.0
or later and be linked using the following switches.  These switches cause
additional information to be included in the image. This information is
necessary to allow Spike to correctly modify the image.

If using MSDEV, add these switches to the linker settings for the project:
	/fixed:no /opt:ref

If using cl directly from the command-line, add these switches:
	/link /fixed:no /opt:ref

If using a Razzle build environment add the following to the sources file:
        USE_PDB=1
        LINKER_FLAGS=/fixed:no /opt:ref


5. UNSUPPORTED/SPECIAL-CASE APPLICATIONS


Some DLL's haved shared sections, which allow different applications
that import the DLL to share data. Applications that use DLL's with 
shared sections require special handling.  If one application that 
imports a shared DLL is instrumented (optimized), then it may be
necessary to instrument (optimize) some or all of the other applications
that import that DLL.

If your application uses a DLL with a shared section, Spike will warn
you.  You can also check yourself by using quickview (Under the file
menu in the explorer) or dumpbin (distributed with Visual C++) to
examine the DLL.

We are currently aware of the following applications/DLL's that
require special handling because of shared sections:

 1. DirectDraw applications import ddraw.dll, which has a
    shared section. Using ddraw.dll has the side effect of
	starting ddhelp.exe (which is located in the system32 directory).
	ddhelp.exe imports ddraw.dll, and the shared section in ddraw.dll
	is used to communicate between ddhelp.exe and the application.
	Thus, if you instrument (optimize) the application, then you
	must also instrument (optimize) ddhelp.exe.

	ddhelp.exe may continue running after the DirectDraw
	application exits.  To be sure that you are running the 
	correct version of ddhelp.exe, you should use the
	task manager to kill any running versions of ddhelp.exe before 
	starting the application.  If you are running an instrumented 
	(optimized) version of ddhelp.exe, its database name will appear
	in the task manager (the database name for ddhelp.exe will be
	ddhelX.exe, where 'X' is some character othe than 'p').  You can 
	find the exact database name for ddhelp.exe by selecting it in the
	image pane of the Spike Manager and then choosing "Image Options"
	from the Image menu.

 2. Microsoft VisualTest 4.0. You must instrument (optimize)
    mt.exe, mtrun.exe, mtscreen.exe, and mtview.exe together.


EDS Unigraphics uses an unusual technique to load the correct
graphics dll. Follow these steps when using Spike to optimize
Unigraphics with the xwi graphics dll:

    1. cd to .../eds111/ugii/uglibs/xwi
    2. start the spike manager by typing "spkmngr"
    3. select "New Application" from the database menu,
       look up one directory to find ugraf.exe
    4. instrument and optimize as usual

To use Spike to optimize Unigraphics with the ogl graphics
dll cd to .../eds111/ugii/uglibs/ogl and follow steps 2-4.


6. USING THE SPIKE OPTIMIZER

To use the spike optimizer:
    
    1. Create an instrumented executable. 
        
          spike -pixie PROG.EXE PROG.PIX

       This will produce two files: PROG.PIX and PROG.fbi.

    2. Run PROG.PIX with representative input.  This will generate a
       feedback file PROG.fbc.  pix.dll must be on the search path.
       Feedback files are placed in the current directory, unless the
       environment variable _SPIKE_FEEDBACK_DIRECTORY is defined.

       The fbc file is not written until the program exits, so be sure
       the process has stopped before using a profile.

    3. Optimize the program:

          spike -Ox -fb PROG PROG.EXE PROG.OPT

        The argument -fb PROG will make spike look for PROG.fbc and PROG.fbi.  You can also
        use -fbi <filename> and -fbc <filename> to specify the full path name for each  file.



To gather multiple feedback files:

    1. Use the -unique switch
     
          spike -pixie -unique PROG.EXE PROG.PIX
        
    2. Run PROG.PIX multiple times with different inputs.  Each run
       will generate a feedback file PROG.xxxxx.fbc.

    3. Merge the feedback files:
          spkmrg PROG.fbi PROG.fbc PROG.*.fbc

    4. Optimize the program as before.

          spike -Ox -fb PROG PROG.EXE PROG.OPT


To instrument DLL's:

    If the program spends a significant amount of time in a DLL, then it is important
    to spike that image as well.  DLL's are handled exactly the same as EXE files.  When
    a DLL is pixified, it will generate its own fbc and fbi files.

    A program finds a DLL by name using the NT search path rules.  A pixified image should
    have the same name as the original DLL so that it will be found.

    To see which DLL's a program uses, you can do a "dumpbin /imports PROG.EXE".  DLL's can
    import other DLL's so you should do a dumpbin recursively.  A program can also explicitly
    load a DLL with the Win32 LoadLibrary function.  These will not show up when using
    dumpbin.


Specifying where the fbc file is dropped:

    If you set the variable _SPIKE_FEEDBACK_DIRECTORY to a directory name,
    the counts files will be dropped in that directory.


Services:

    It is possible to spike a service.  Setting the _SPIKE_FEEDBACK_DIRECTORY will not work
    for a service.  All the services we have tried have dropped the fbc files in the system32
    directory.


Persistent database:

    This version of spike supports a "persistent" feedback database.  Spike
    can be used to optimize a version of PROG.EXE that differs from the
    version used to collect feedback.  Spike will report whether the changes are
    significant.

------------------------------------------------------------------------
