<<>>
<<SpyDoc.tioga>>
<<Michael Plass, September 22, 1992 1:13 pm PDT>>
<<>>
Spy
CEDAR 10.1    
Spy
A stack-tracing performance tool for PCedar
Michael Plass
©  Copyright 1990, 1991 Xerox Corporation. All rights reserved.
Abstract: This is the data-collection part of the PCedar Spy.  See the SpyTool for the data analysis.
Created by: Michael Plass
Maintained by: Michael Plass:PARC:Xerox
Keywords: performance measurement, tuning, memory allocations, timing, CPU usage

XEROX            Xerox Corporation
                Palo Alto Research Center
                3333 Coyote Hill Road
                Palo Alto, California 94304


News
September 22, 1992 - added the ability to specify offsets when using SpySetTraceBreak.
December 13, 1991 - added the ability to spy on SIGNALs and ERRORs.  New switches to SpyStart is -s.
June 28, 1991 - added the ability to turn the output of du (the UnixTM disk usage utility) into a spy log usable by the SpyTool.  
New command is SpyDUFilter.
May 17, 1991 - added the ability to spy on allocations and words allocated (without having to rely on setting breakpoints in the 
allocator).  New switches to SpyStart are -a and -w.
Introduction
    The Spy is designed to be the main tool for analyzing the performance of programs in PCedar.  With the Spy, the programmer can see 
    which procedures are consuming CPU cycles, which are using the allocator, or which are calling a particular procedure.
    The main paradigm of the Spy is to record the call stack of an interesting process.  The definition of "interesting" varies 
    according to what the Spy is measuring.  If the Spy is measuring CPU usage, it records the stack of the top-most active process 
    at regular intervals.  The only things recorded are the procedures in the call stack; parameters and local variables are not 
    recorded.
    The PCedar spy is a new implementation, based on the concepts of both the Interlisp Spy by Larry Masinter and the DCedar Spy by 
    John Maxwell.
Commands
    These commands may be used to start and stop the Spy from a Commander.
        SpyStart  Start the spy.  Arguments:
            -a       => watch allocations
            -w    => watch words allocated
            -t       => watch thread switches (default)
            -s    => watch SIGNALs and ERRORs
            -n <n> => preallocate n spy tree nodes (default 10000)
        SpyStop  Stop the spy, write results to specified file (or to standard out, if no argument is provided).

    These commands are for setting spy breaks.
        SpyClearBreaks       Clear all spy breaks
        SpySetTraceBreak     <cprocname> - set a spy trace break

    This command is a filter to add total counts to a disassembly listing:
        SpyPCFilter          Prepend counts onto disassembled code.
                             args: spy log name(s)
    This may occasionally be useful for instruction-level tuning.  The counts are cumulative, so tallys on call instructions include 
    the samples for all the callees.  (Self-calls will thus be overcounted).

    This command turns the output of the du (the UnixTM disk usage utility) into a spy log usable by the SpyTool:
    SpyDUFilter          Convert output of du command into a spy log
    Arguments are file names, output file names are suffixed with ".spy".  An argument of "-" reads from standard input and writes to 
    standard output.
Examples
% -- watch cpu usage
% SpyStart
% dosomething
Failed in PreRegister dosomething: No .command or .cm file found for dosomething
% SpyStop cpu.spy
% SpyTool cpu.spy
% -- watch allocations
% SpyStart -a
% dosomething
Failed in PreRegister dosomething: No .command or .cm file found for dosomething
% SpyStop allocations.spy
% SpyTool allocations.spy
% -- watch words allocated
% SpyStart -w
% dosomething
Failed in PreRegister dosomething: No .command or .cm file found for dosomething
% SpyStop wordsAllocated.spy
% SpyTool wordsAllocated.spy
% du . >exampledu
% SpyDUFilter exampledu
% SpyTool exampledu.spy
% 
TraceBreak Examples

% SpySetTraceBreak _XR_NewObject
Break set at pc=0008F6E3CH
% SpyStart -~t
% -- You probably want to say -~t when using breaks
% dosomething
Failed in PreRegister dosomething: No .command or .cm file found for dosomething
% spystop breaks.spy
% spytool breaks.spy
% SpyClearBreaks
Clearing break at pc=0008F6E3CH ...Ok.
% 

It is on occasion useful to set the break a little bit into the procedure, so more meaningful information is available on the 
stack; for a SPARC, you want to be past the save instruction, which is usually the first or second instruction of a procedure.  To 
do this, you may use an offset:

% Disassemble _TransformOp_P2640 | head
PSGraphicsPrimitivesImpl._TransformOp_P2640
00B8807C: 9DE3BF80 save  %o6,-128,%o6
00B88080: F227A048 st    %i1,[%i6+72]
00B88084: F427A04C st    %i2,[%i6+76]
00B88088: F8062088 ld    [%i0+136],%i4
00B8808C: 11002F4C sethi &hi(0x00BD3000),%o0 ! 0x00BD3000
00B88090: EE070000 ld    [%i4],%l7
00B88094: D2062020 ld    [%i0+32],%o1
 {   0.21 sec }
% SpySetTraceBreak _TransformOp_P2640+4
Break set at pc=000B88080H
 {   0.01 sec }
% SpyStart -~t
 {   0.05 sec }
% dummyprint ppos112.ps
Opening ppos112.ps
0.39 elapsed seconds to alloc map and open ppos112.ps
Postscript file: ppos112.ps, spi: 300, copies: 1
Copy 1:  [1]
Done in 18.81 (17.86) seconds (ppm: 3.2).

 {  19.40 sec }
% spystop ppos112.spy
 {   0.53 sec }
% spytool ppos112.spy
 {   0.25 sec }
% SpyClearBreaks
Clearing break at pc=000B88080H ...Ok.
 {   0.01 sec }
% 
Client interface

Spy.mesa provides a client interface to the spy, in case somebody wants a different UI.  Also, the use of Spy.SampleMyStack is a 
way to instrument code yourself.
See Also
SpyToolDoc.tioga tells you how to use a viewer-based tool for interpreting the results.   SparcAidsDoc.tioga tells you about the 
Disassemble command.