head     1.1;
access   ;
symbols  ;
locks    ; strict;
comment  @# @;


1.1
date     89.03.08.10.57.02;  author quist;  state Exp;
branches ;
next     ;


desc
@Documentation for the files SPY, COVERAGE, PTESTS, SBUILDER, SCANLIST and TRAP0M
RDQ
8 mar 1989
@



1.1
log
@Initial revision
@
text
@                                          SPY
                           A SET OF TOOLS TO MEASURE/RECORD
                               ACTIVITIES IN PASCAL CODE
                           
files :

  TRAP0M        An Assembly module, allows Pascal code to use the TRAP #0 vector.
  
  SPY           A Pascal program to collect and report information about running code.
  
  SBUILDER      A Pascal program to generate a stream file for generating code files
                with line numbers modified to help SPY collect coverage data.
               
  SCANLIST      A Pascal program to collect information on source lines from either
                Pascal compiler listings or Librarian Unassembly listings.  It can
                modify line numbers to help SPY collect coverage data.
                
  OPTIMIZER     A Pascal program to convert Librarian Unassembly listings into
                Assembler source files.  (It can optionally perform some code
                optimizations, but that option is not used in this situation)
  
  COVERAGE      A stream file to prepare a code file for coverage testing by SPY.
                  

                               
more details :
        
                                    TRAP0M        
        
             defines module T0_SUPPORT

        src     MODULE T0_SUPPORT;
        src     EXPORT
        src     TYPE
        src     lineproc = procedure(lnum : integer);
        src     VAR
        src     trap0hook : lineproc;
        src     lastline  : integer;
        src     a6reg     : integer;
        src
        src     PROCEDURE START_MONITOR;
        src     PROCEDURE END_MONITOR;
        src     END;
        
        START_MONITOR
            Adjusts the TRAP #0 vector so that trap0hook is called
            whenever a TRAP #0 exception is executed.

        END_MONITOR
            Restores TRAP #0 operations to system normal.
            
        When trap0hook is called, its argument is the 16 bit value normally)
        a line number) encoded immediately after the TRAP #0 instruction.
        
        lastline   contains the 32 bit absolute address of the 16 bit value.
        if lastline were a ^shortint then lastline^ would be the same value
        as the argument.
        
        a6reg      contains the value of register A6 at the time the TRAP #0
        instruction was executed.  (this is the stack frame register)
        
        trap0hook  can not be an nested procedure.  (ie the static link is
        ignored) This is to maximize the speed of execution which is already
        not great.
        
        trap0hook must be set before START_MONITOR is called.
        
        
                                       SPY     
        
             A Pascal program to collect and report information about running
        code.  By using the T0_SUPPORT model, SPY can collect information
        about a running program or module.
        
             It operates by collecting information in an array of 65536
        integers The maximum line number is 65535, so there is one entry for
        each possible line number.  Because the program collects data during
        the execution of other code, it always P loads its self.
        
             The is also an array used to keep track of which line numbers
        are supposed to exist in a module/program under test.  This array is
        built by other programs and written to the file SRCSTATS.  SPY reads
        this file.
        
             SPY collects different kinds of information by plugging different
        procedures into trap0hook.
        
             There are currently 4 different procedures.
        
             C counts the number of times a particular line number was 
               executed.
        
             D records whether or not a line number was executed.  This mode
               is used in coverage testing. (more about this mode later)
               This mode is some times called the coverage mode and sometimes
               called the Dead code check mode.
        
             H simply records the line numbers in the order in which they 
               were executed.  This is like the debugger's history queue
               except that 131070 line numbers can be recorded instead of
               just the 64 lines of the debugger.
        
             P records the amount of time spent in a procedure/function
               This time includes any time spent in lower level procedures
               or functions.
        
             SPY is driven by single letter commands which invoke the 
        following actions:
        
             Begin, End, Report, Save, Load, Quit
        
             Begin (B)
                
             Activates the trap0hook.  Will prompt for the recording mode: 
        Count, Dead_code_check, History These correspond to the three
        recording procedures.  If the Mode selected is different from the
        previous mode then the run stats array will be cleared otherwise the
        user will be asked if the stats should be cleared.
        
             The message  Monitoring started  shows that the trap0hook has
        been activated.
        
             End  (E)
        
             Deactivates the trap0hook.   The message Monitoring ended shows 
        that the trap0hook has been deactivated.
        
        
             Report (R)
        
             Begins display of the information collected thus far.  It may be
        best to issue an End command before issuing the Report command.
       
             For mode :
        
             C    Line Count Report
                  
                  The format of the report is
                  line ..  line count
                  
                  The  .. line is given where consecutive lines have the same
                  count value. 
        
             D    Coverage Report
                  
                  This report has several options, each of which is produced 
                  in response to a prompt.  It will read the SRCSTATS file.
                  (this file is produced by the SCANLIST program)
                  
                  Report
                  Source statements not executed (Y/N) ?
                    
                  Will eventually produce a list of line numbers which appear
                  in the source stats but not in the run stats.
                 
                  Reports the lowest, highest line number and the number lines in
                  the SRCSTATS file.
                  
                  Report
                  Executed statements with no source (Y/N) ?
                  Will report the line numbers which appear in the run stats 
                  but do not appear in the source stats.  Any lines here 
                  would mean that code with debug on was executed but not 
                  reported to the SCANLIST program.
                  
                  Execution stats will be reported, including the percentage
                  of SRCSTATS statements executed.
                  
                  Show unexecuted source (Y/N) ?
                  Will prompt for 
                  Name of Listing File
                  
                  This is the name of the file containing the compiler
                  generated source listing of the code under test.  The DEBUG 
                  ON compiler directive must be present.
                  
                  The source lines for those lines which appear in the file 
                  but not in the run stats array will be displayed.
                  
              
             H    History Report
                  
                  After reporting the total number of lines recorded, the
                  program will ask if the user wants to Source step thru the
                  lines.
                  
                  If the answer is <> Y then a dump of the line numbers will
                  be given with a space every 10 lines and a pause every 50
                  lines. On the pause, pressing the space key or return key
                  will continue the dump, any other key will abort the
                  report.
                  
                  If the answer is Y then the user will be prompted for the
                  Name of Listing File
                  
                  This is the name of the file containing the compiler
                  generated source listing of the code under test.  The DEBUG 
                  ON compiler directive must be present.  Information is 
                  displayed with an index number followed by the line from
                  the source file.  The index shows the position in the
                  recording array and therefore shows different executions
                  of the same line.
                  
                  Once in the single step mode, the following commands apply:
                  
                  uparrow or space key : advance the index & display the line. 
                  
                  down arrow           : decrement the index & display the line.
                  
                  Q                    : abort the report.
                  
                  F                    : find a particular line number.
                  The user is prompted to enter the line number.  A positive
                  value will scan forward from the current index, a negative
                  value will scan backward from the current index.  If the
                  line number is not found then the a message is given and 
                  the current line number is displayed again.
                  
             P    Performance Report
                   
                  The report has 3 columns.
                  A line number, the number of milli seconds associated with
                  each line number and the percentage of total time.
                  
                  The line number is the first executed line number of a 
                  procedure, function or main program.
                  
                  At the bottom of the report is the total time covered by the
                  report.  The time starts with the first line executed and
                  ends with the last line executed.  These two times are
                  recorded in the line number 0 and line number 1 positions, so
                  these two line numbers must not appear in the code under test.
                  
                  The system 4 micro second clock is used to calculate elapsed times
                  but it is reported in milli seconds.
                  
                  There is a limit of 50 levels of calls.  This may be a problem
                  for code which uses recursion.
        
        Save      
        
                  This command will prompt for a file in which to save the
                  current run stats array.  The array will then be written to
                  the file.
                  
        Load
                  This command will prompt for the name of a file containing
                  a Saved run stats array, then read that file.  Reports may
                  then be generated.
  
                                       
                                       SCANLIST
        
             A Pascal program to collect information on source lines from
        either Pascal compiler listings or Librarian Unassembly listings.  It
        can modify line numbers to help SPY collect coverage data.
        
             Prompts for the name of a Pascal Compiler listing file or a 
        Librarian Unassembly listing file.
        
             Asks if the stats are to be cleared.  A yes answer will cause
        SRCSTATS file to be read and a summary of the contents reported.
                
             If the file is a Librarian file, the user will be asked if line
        numbers are to be adjusted. (this would be to assist in the coverage
        report by SPY) 
        
             A problem arrises when multiple statements are coded on the same
        source line as commonly occurs in an IF xxxxx THEN tttt ELSE eeee;
        statement.  The line number as encoded by the compiler can not be
        used to identify which branch of the IF was taken.  This option in
        SCANLIST will use the high order two bits of the 16 bit line number
        to identify each statement.  This reduces the avaliable line number
        range to 0..16383 and will only identify the first four statements on
        a line.  So some care must be exercised in using this option.
        
             If the line numbers are to be adjusted, the user is also 
        prompted for a new file in which to write the adjusted source.
        The default name is NEWFILE.TEXT .
        
             The program also produces a summary report of the line numbers
        it found and writes the SRCSTATS file for later use by SPY or 
        a later execution of SCANLIST.
        
             NOTE  If multiple source files are to be tested at once, the
        Compiler Listing files will have to be combined manually (eg use the
        Editor) if Source stepping or or Unexecuted source reports are to
        be done by SPY .  It will probably be necessary to make use of the
        LINENUM compiler directive in order to ensure unique line numbers
        thru out the code under test.
        
                                       
                                       SBUILDER

             A Pascal program to generate a stream file for generating code
        files with line numbers modified to help SPY collect coverage data.
                                       
             This program expects as input a file named JUNKL.TEXT .  This
        file must have been created by the Librarian's F directive.  The F
        directive creates a list of all of the modules in a code file.
        
             The stream file when streamed, will replace the code file
        (named in JUNKL.TEXT) with a code file which has adjusted line
        numbers (see program SCANLIST) to do this, the following
        actions are taken:
        
             Given JUNKL.TEXT, produce and optionally stream JUNKS.TEXT .
        For each module in the code file,
        use the Librarian to produce an Unassembly listing in JUNK1.TEXT .
        use SCANLIST to adjust line numbers and produce a file JUNKN.TEXT .
        use OPTIMIZER to convert JUNKN.TEXT to JUNK1.TEXT (assembler source)
        use ASSEMBLER to assemble JUNK1.TEXT to JUNK1.CODE
        use Librarian to copy JUNK1.CODE into a JUNK2.CODE
        when all modules have been processed, 
        use FILER to change JUNK2.CODE to original .CODE file
        and remove JUNKL.TEXT, JUNKN.TEXT, JUNK1.TEXT, JUNK1.CODE and
        JUNKS.TEXT .
        
             The stream file (JUNKS.TEXT) may optionally be streamed by the
        program.
                                    
                                   
                                      OPTIMIZER 
        
             A Pascal program to convert Librarian Unassembly listings into
        Assembler source files.  (It can optionally perform some code
        optimizations, but that option is not used in this situation)
  
  
                                       COVERAGE
        
             A stream file to prepare a code file for coverage testing by
        SPY.  This file prompts for the name of the source file without the
        suffix (.TEXT is assumed).  This file is compiled and a listing file
        with suffix .ASC is generated.  The Librarian is invoked to produce
        the JUNKL.TEXT file required by SBUILDER.  SBUILDER is executed and
        told to have SCANLIST clear stats for the first module processed and
        to immediately stream JUNKS.TEXT .
        
             A copy of the file is included below.

=FName of TEXT file containing $DEBUG ON$ (do not type the .TEXT suffix)
c@@F
l@@F.ASC

li@@F
pJUNKL
fq

xSBUILDER
YY




@
