! General-Purpose Post Processor (gpp) Online Help
!
! $Id: gpp.hlp,v 2.0 1994/07/15 02:41:50 src v3-4-a-beta1 $
! CONFIDENTIAL
!	 Copyright (c) 1990 by Synopsys, Inc.
!       ALL RIGHTS RESERVED
!  This program is proprietary and confidential information of
!  Synopsys, Inc. and may be used and disclosed only as authorized 
!  in a license agreement controlling such use and disclosure.
!
! $Author: src $
! $Date: 1994/07/15 02:41:50 $
! $Locker:  $
! $Source: /am/barnacle/remote/dtg313/src/sim/jer/dev/admin/IMAGE/doc/sim/help/RCS/gpp.hlp,v $
! $Revision: 2.0 $
! $State: v3-4-a-beta1 $
! Revision 2.11  88/04/26  16:58:15  bond
! Update analyzer description.
! 
>
>General Purpose Post-Processor (gpp) Internal Help -- 15 September 1989
>
>Help is available for each command by invoking 'help <keyword>'.
>For a list of all available keywords, type 'help all'.
!
% all
!
>
>Help is available for the following:
>
>Commands:
>  compare      help           load           show        utilization
>  default      histogram      pop            statistics
>  dump         include        push           timespec
>  files        list           quit           unload
>
>Defaults (a.k.a. attributes):
>  base         dtlimits       hprecision     nticks
>  bounds       file           hwidth         tbase
>  columns      hbuckets       iecho          timechange
>  compare      hmode          limits         timespec  
>
>Other Topics:
>  attrlist     commands       filespec       timerange
>  basespec     comments       monspec        shell
>  basics       restrictions   numbers
>
>You may want to check `basics' if you are not acquainted with gpp or its
>predecessor, spp.
!
!  ====================
!    Commands Section
!  ====================
!
% default
!
>
>> default                         ! inquires all settings
>> default <attribute_list>        ! set/inquire default attributes
>
>The default command allows the user to set default values for arguments
>and attributes to other commands.  These default values are used when the
>user does not make an explicit declaration in the command.  The current
>value for a default attribute can be listed by not supplying a new value
>for the attribute.  The following attributes are supported:
>
>  base         dtlimits       hprecision     nticks
>  bounds       file           hwidth         tbase
>  columns      hbuckets       iecho          timechange
>  compare      hmode          limits         timespec  
>
>Examples:
>     > default hbuckets 30    ! sets the default buckets to 30
>     > default hbuckets=      ! inquire current setting
>     hbuckets = 30
>     > default file; tbase = sdv   ! inquire file; set tbase
>     default file = simulation.d (index = 1)
>
>See also:
>     attrlist, or any of the attributes listed above
!
% dump
!
>
>> dump
>> dump all
>> dump <monitor_spec> ...
>
>The dump command displays monitor events over a particular time range.
>If no arguments are given to the dump command, all events in the specified
>time range are printed in the order they occurred in the trace data file.
>The argument 'all' produces events for every monitor defined in the trace
>file in turn.  The last form of the command allows the events of individual
>monitors to be dumped.
>
>The output format of the dump command is similar to that obtained
>from the running n2 simulator.
>
>Attributes used by this command include:
>     bounds                ! restricts dump to smaller time range
>     file                  ! where to look for trace monitors
>     base, sbase, tbase    ! for formatting data
>
>Examples:
>     > dump {bounds=100,$}          ! dump all events in the default file from
>                                    !   time 100 to the end of the trace file
>     > dump 3 {file=2; bounds 100,200}   ! dump of tag 3 in file 2 from time
>                                         !   100 to time 200
>     > dump cpu:pc                  ! dump of named structure
>
>See also:
>     monspec, bounds, file, commands
!
% examine
!
>
>> examine all
>> examine <monitor_spec> ...
>
>The examine command is currently not implemented.
!
% files
!
>
>> files
>> files all
>> files <file_spec> ...
>
>The first form of this command prints a short summary of each trace file
>that has been loaded into this execution of gpp.  Listed is the file 'index',
>which can be used to identify trace files in other commands.
>
>The second form of this command, ('files all'), prints out a long summary
>of each trace file that has been loaded into this execution of gpp.
>
>The final form of this command prints out a long summary of each
>of the named files.
>
>No attributes are used by this command.
>
>See also:
>     filespec
!
% help
!
>
>> help
>> help <keyword>
>
>The help command provides online command syntax information.
>
>Examples:
>     > help default   ! returns information available on 'default'.
>     > help all       ! returns list of all available help.
>
>No attributes are used by this command.
!
% histogram
!
>
>> histogram all
>> histogram <monitor_spec> ...
>
>The histogram command displays a value histogram of trace data values
>or delta time components.  The histogram is constructed by defining a
>range of values of interest.  This range is the divided into 1 or more
>'buckets'.  Each time the trace is written with a value, the count of
>the appropriate bucket is incremented.
>
>The histogram is displayed using simple text-based graphics.
>
>Attributes used by this command include:
>      base         ! used to display bucket value ranges; the sign-
>                   !  indicator determines whether signed or unsigned
>                   !  arithmetic is used.
>      bounds       ! defines the time bounds of interest
>      limits       ! defines the data range of interest
>      dtlimits     ! defines the delta time range of interest
>      hmode        ! decides whether data or delta time will be histogrammed
>      hbuckets     ! number of buckets to use; used if hwidth is 'auto'
>      hwidth       ! width of each bucket
>      hprecision   ! number of references per asterisk; may be set to 'auto'
>
>Examples:
>     > histo 5 {limits 55,144; hwidth 10}   ! 9 buckets, each containing
>                                            ! 10 data values ranging from
>                                            ! 55 to 144
>
>Notes:
>     The 'base' attribute should be set to some right justified indicator
>     so that the rows of asterisks line up.  The 'limits', 'hbuckets', and
>     'hwidth' attributes may be set so that there is a remainder when
>     bucket number and width are calculated.  This remainder is always added
>     to the last bucket, so the last bucket may be somewhat "heavy".
>
>See also:
>     base, bounds, hbuckets, hmode, hprecision, 
>     hwidth, limits, monspec, commands
!
% include
!
>
>> include <file_spec> ...
>
>The include command tells the postprocessor to read and interpret a
>text file as a sequence of commands.
>
>In this context, the file specification must be a file name.  The only
>attribute used by this command is the 'iecho' attribute.
>
>If the include file name contains special characters, the name should
>be enclosed in double quotes.
>
>Examples:
>     > include startup.cmds
>     > include "/mnt/user/n2/cmds"
>
>Include files can be nested ( one can 'execute' another), but they
>may not be recursive.
>
>See also:
>     filespec, iecho, commands
!
% load
!
>
>> load <file_spec> .....
>
>The load command instructs the program to read a trace data file
>and build internal data structures that contain the data.  It is
>impossible to analyze data in a file until the file has been read in.
>
>Note that one or more trace file names may be specified on the
>gpp command line.  gpp will read those in before prompting for
>commands.
>
>More than one file name can be specified to the 'load' command.
>
>The 'files' command reports on trace files already read.
>
>The last file read in sets the 'file' default attribute.
>
>In this context, a file_spec may not contain a file index -- the
>file must be specified by its name.  Also, in this context the '.d'
>extension may be omitted.
>
>This command uses the attribute 'bounds', which specifies loading only a 
>portion of a trace file.
>
>Example:
>     > load t.d {bounds ^,500}  ! load file 't.d' from its beginning to
>                                ! simulated time 500.
>
>See also:
>     filespec, bounds, unload, commands
!
% list
!
>
>> list                        ! list monitors in the default file
>> list all                    ! list monitors in all loaded files
>> list <file_spec> ...        ! list monitors in the trace file
>                              ! specified
>
>This command lists the trace command monitors found within
>a trace data file.  Information listed includes tag number and monitor
>name, which are used as monitor specifications (see 'monspec').
>
>Without an argument, list lists the contents of the current 'default'
>file.  You can also specify a trace file index number (or file name)
>to report on the monitors within that particular file.
>
>See also:
>     filespec, monspec, commands
!
% push
!
>
>> push
>
>The push command saves the values of the current global attributes on the
>attribute stack.  These values can later be restored by a pop command.
>Push...pop command pairs can be nested.
>
>See also:
>     pop, default
!
% pop
!
>
>> pop
>
>The pop command removes an entry from the top of the attribute stack and
>uses it to set the values of the global attributes.  Entries are added to
>the stack by push commands.  For every pop command, there must have been
>a previous "unpaired" push command.  Push...pop command pairs can be
>nested.
>
>See also:
>     push, default
!
% quit
!
>
>> quit
>
>The quit command causes the program to terminate.  It may be executed
>from within include files.
!
% run
!
>
>> run all
>> run <monitor_spec> ...
>
>The run command is currently not implemented.
!
% statistics
!
>
>> statistics all
>> stat <monitor_spec> ...
>
>The statistics command reports univariate statistics for the specified
>trace monitors.
>
>These include minimum value, maximum value, sample mean, sample variance,
>sample standard deviation, time average, time variance, and time standard
>deviation.  (Note: See 'restrictions'.)
>
>Attributes used by this command include:
>     base     ! used to display the minimum and maximum values, other
>              !  values are always reported as decimal floating point
>              !  numbers;  the sign indicator determines whether signed
>              !  or unsigned arithmetic will be used.
>     bounds   ! used to limit the range of time considered
>     limits   ! used to limit the range of data values considered
>
>Examples:
>     > statistics 3 4{bounds ^,$}  ! report statistics for monitor 3 over
>                                    ! the default time bounds, and for
>                                    ! monitor 4 over the whole trace file
>
>See also:
>     monspec, base, bounds, limits, commands, restrictions
!
% unload
!
>
>> unload all
>> unload <file_spec> ...
>
>The unload command reclaims the internal storage associated with each of the
>named files.  Trace files which have been unloaded may not be analyzed by
>the postprocessor.  The command 'unload all' empties the postprocessor trace
>file database.
>
>See also:
>     filespec, load
!
% utilization
!
>
>> utilization all
>> util <monitor_spec> ...
>
>The utilization command gives information about the time component of the
>trace monitor.
>
>For every value the trace assumes over the specified time range, the
>following statistics are reported:
>     count      (the number of times the trace monitor assumed that value),
>     time       (the total amount of simulated time that the trace monitor 
>                 had that value), 
>     %_of_total (percent of total time that the trace monitor had that value),
>     min        (minimum length of time for which the trace monitor had that 
>                 value), 
>     max        (maximum length of time for which the trace monitor had that 
>                 value), 
>     mu         (the average length of time for which the trace monitor had 
>                 that value), and 
>     sigma      (the sample standard deviation of those times).
>
>Attributes used by this command include:
>     base     ! used to display the data values, other values are always 
>              !   reported as decimal floating point numbers;  the sign 
>              !   indicator determines whether signed or unsigned arithmetic 
>              !   will be used.
>     bounds   ! used to limit the range of time considered
>     limits   ! used to limit the range of data values considered
>
>Example:
>     > util 5 {base=rdu}  ! Print utilization information for trace monitor 5;
>                          !   print data values in base 10 right justified;
>                          !   use unsigned arithmetic.
>
>See also:
>     monspec, base, bounds, limits, commands
!
% show
!
>
>> show ['{' <attribute_list> '}'] all
>> show ['{' <attribute_list> '}'] <object> [ [','] <object> ]...
>
>where:
>     object ::= <monitor_spec> | <timespec_name>
>
>The show command is used to display information about monitors or to display
>previously entered time specifications.  The <object> can be the name of a
>time specification, in which case the time specification is displayed, or the
>name of a monitor, in which case information about the monitor is displayed.
>If the command 'show all' is entered, all of the currently defined time
>specifications are displayed followed by information on all of the monitors
>for the default trace file (unless overridden by the 'file' attribute).
>
>Attributes used by this command include:
>     file      ! for monitors, indicates which loaded file to use
>
>Examples:
>     > show {file = 2} all                     ! show all time specifications;
>                                               !   show all monitors from file
>                                               !   index=2
>     > show t1, t2, mon1                       ! show time specifications t1
>                                               !   and t2; show mon1 from
>                                                   default trace file
>     > show {file=2} mon1 mon2 {file=1} mon3   ! show mon1 and mon3 from file
>                                               !   index=2 and mon2 from file
>                                               !   index=1
>
>See also:
>     timespec, monspec, file, attrlist
!
% compare
!
>                             COMMAND
>
>> compare [<ablock1> [<ablock2>]] <mon_list1> to [<ablock3>] <mon_list2>
>
>where:
>     <ablock>   ::= '{' <attribute_list> '}'
>
>     <mon_list> ::= all | <monitor_spec> ...
>
>The compare command matches up the monitors in <mon_list1> to the monitors in
><mon_list2> and compares them for equivalence using the time specification
>currently in effect.  Any differences found are displayed.  Any attributes
>specified in <ablock1> override any global attributes and apply to all 
>comparisons in the command.  Attributes specified in <ablock2> override the
>command attributes and apply to the monitors in <mon_list1>.  Attributes 
>specified in <ablock3> override the command attributes and apply to the 
>monitors in <mon_list2>.  Note that individual monitors may have associated
>attribute lists that override <ablock1>, <ablock2>, and <ablock3>, as
>applicable.
>
>The 1st monitor in <mon_list1> is compared to the 1st monitor in <mon_list2>;
>the 2nd monitor in <mon_list1> is compared to the 2nd monitor in <mon_list2>;
>the 3rd monitor in <mon_list1> is compared to the 3rd monitor in <mon_list2>;
>and so on until one or both of the monitor lists is exhausted.
>
>Attributes used by this command include:
>     base       ! controls the display format of the monitor data
>     compare    ! controls whether or not all comparisons are displayed
>     bounds     ! determines the restrictions on the simulation times compared
>     file       ! specifies to which trace file a monitor belongs
>     timespec   ! specifies the simulation times to be used in the comparison
>
>Examples:
>     > compare mon1 to mon2
>     > compare mon1 {timespec=t1} to mon1 {timespec=t2}
>     > compare mon1, mon2 to {timespec=t2; file=2} mon1 mon2
>     > compare {compare=show_all} {file=1} all to {file=2} all
>
>Notes:
>     o When the compare command starts comparing a pair of monitors, it sets 
>       the current simulation time to the lower time bound (usually zero).
>     o The compare command ignores zero-time transitions in monitors.  Only
>       the monitor value at the end of each simulation time is compared.
>     o The compare command stops a monitor comparison if a simulation time
>       outside the current time bounds is requested.  Comparison also stops
>       when all of the times specified in a time specification have been used.
>
>See also:
>     timespec, base, bounds, file, attrlist, monspec
>
>                             DEFAULT
>
>> default compare ['=']                ! inquires current setting
>> default compare ['='] show_all
>> default compare ['='] noshow_all
>
>This attribute only affects the 'compare' command.  If the value is 
>'show_all', the compare command will show the results of every monitor 
>comparison it makes.  If the value is 'noshow_all', the compare command only
>shows comparison results when the monitors differ.  The initial value is 
>'noshow_all'.
!
% timespec
!
>                             COMMAND
>
>The timespec command specifies a (possibly infinite) series of simulation
>times to be used in a compare command.  You can specify individual times or
>ranges of times.  You can even repeat a set of times.  That said, here is
>the syntax:
>
>> timespec <timespec_name> ['=' | is] <time_specs_list>
>
>where:
>     <time_specs_list> ::= <time_specs> [ ',' <time_specs> ]...
>
>     <time_specs> ::= <time_spec> |
>                      repeat <rpt_count> <time_specs_list> [ end ] |
>                      from <time_spec> to <time_spec> [ end ] |
>                      [ '+' ] all
>
>     <rpt_count> ::= forever | <time_expr> times
>
>     <time_spec> ::= [ '+' | '-' | '@' ] <time_expr>
>
>     <time_expr> ::= <time_term> | <time_expr> <add_op> <time_term>
>
>     <add_op> ::= '+' | '-'
>
>     <time_term> ::= <time_primary> | <time_term> <mul_op> <time_primary>
>
>     <mul_op> ::= '*' | '/' | '%'
>
>     <time_primary> ::= [ '+' | '-' | '@' ] <time_element>
>
>     <time_element> ::= <number> | '(' <time_expr> ')' | '^' | '$' | '~'
>
>Don't be afraid of the syntax.  Most of it is just stuff that you and 
>everybody else takes for granted.  For example, the syntax from <time_expr>
>to <time_element> is your standard math, with multiplication (*), division
>(/), and modulus (%) taking precedence over addition (+) and subtraction (-).
>
>The unary operators in the <time_primary> expression are positive (+), negate
>(-), and exactly (@).  In the <time_spec> expression, these operators have a
>completely different meaning: forward-in-time (+), backward-in-time (-), and
>at-the-time (@).
>
>The other special symbols are:
>     ^ = lower time bound (usually the beginning of simulation time)
>     $ = upper time bound (usually the end of simulation time)
>     ~ = the current simulation time (i.e. the most recent simulation time
>         used in the compare command)
>
>The 'repeat' expression repeats the specified <time_specs_list> indefinitely
>('forever') or a finite number of times ('<time_expr> times').  The 'from'
>expression specifies a range of times.  Specifying 'all' or '+all' is the
>same as specifying 'from ^ to $ end'.
>
>And now, what you have been really waiting for, examples:
>     > timespec t1 = 1, 2, 3, 4                  ! times 1, 2, 3, and 4
>     > timespec t2 = +1, ~+2, +3, ~+4            ! times ~+1, ~+3, ~+6, and
>                                                 !   ~+10
>     > timespec t3 is ^, repeat forever +2 end   ! every other simulation time
>     > timespec t4 = from +($-^)/3 to +($-^)/2   ! from a third of the way
>                                                 !   through the simulation to
>                                                 !   a half of the way through
>     > timespec t5 = 0, repeat forever from +1 to +10, +90
>                                                 ! times 0-10, 100-110, 
>                                                 !   200-210, 300-310, ...
>
>See also:
>     bounds, attrlist
>
>                             DEFAULT
>
>> default timespec ['=']                ! inquires current setting
>> default timespec ['='] <timespec_name>
>
>The timespec attribute specifies the time specification that is to be used
>in subsequent compare commands, or if specified in an attribute block in a
>compare command, the time specification to be used in that compare command.
>
>The initial value of the timespec attribute is not defined.  The compare 
>command treats an undefined timespec attribute as 'from ^ to $ end' (i.e. 
>from the lower time bound to the upper time bound, usually the beginning and 
>end of simulation time).
!
!  ====================
!    Defaults Section
!  ====================
!
% base
!
>
>> default base ['=']                    ! inquires current setting
>> default base ['='] <basespec>
>
>The base default determines how data will be displayed by the postprocessor.
>Initially hexadecimal with leading zeros shown.  Note that control and time 
>information are normally displayed as decimal numbers.  
>
>The sign indicator of this attribute is used to determine whether data should
>be interpreted as signed or unsigned in internal postprocessor computation.
>
>See also:
>     default, basespec, sbase, tbase, attrlist
!
% bounds
!
>
>> default bounds ['=']
>> default bounds ['='] [<time_bound>] [',' <time_bound>]
>
><time_bound> ::= '^' | '$' | <number>
>
>The bounds default is used to restrict the time range considered by a
>command.  It is initially set to ^,$ which means all available time.
>
>'^' stands for the lowest available time, '$' stands for the highest
>available time.
>
>Examples:
>     > default bounds ^,1000            ! from lowest time in file to 1000
>     > ...command... {bounds=,300} ...  ! only change upper time bound
>     > ...command... {bounds 400} ...   ! only change lower time bound
>
>See also:
>     default, attrlist
!
% columns
!
>
>> default columns ['=']
>> default columns ['='] <number>
>
>The columns default lets the post processor know how many printing columns
>it has to work with.  The initial value is 80.
>
>Example:
>     > default columns=132    ! for 132 column terminals/printers
>
>See also:
>     default, attrlist
!
% dtlimits
!
>
>> default dtlimits ['=']
>> default dtlimits ['='] [<low_bound>] [',' <high_bound>]
>
><low_bound> ::= '^' | <number>
><high_bound> ::= '$' | <number>
>
>The dtlimits default allows the user to restrict the range of delta
>times considered by a command.  This default is initially set to ^,$
>which means all trace records will be considered.
>
>It is possible to set only one of the limits.
>
>Examples:
>     > default dtlimits ,60            ! set upper limit only to 60
>     > ...command... {dtlimits=20,$}   ! set both limits
>
>See also:
>     default, attrlist, histogram
!
% file
!
>
>> default file                  ! examine current default trace file
>> default file=4                ! set default file
>> default file data.d           ! set default using file name
>
>This default sets the trace data file which is the subject of
>all further commands, until another 'default file' is executed.
>The trace file may be specified either by its numeric index,
>or by its name.
>
>The 'files' command (without arguments) will describe all files
>already read in.
!
% hbuckets
!
>
>> default hbuckets ['=']
>> default hbuckets ['='] <number>
>
>Hbuckets is a default.  It sets the number of value divisions for
>histograms.
>
>Examples:
>     > default hbuckets =         ! examine current value of hbuckets
>     hbuckets = 10
>     > default hbuckets 100       ! set histogram buckets to 100
>
>See also:
>     default, attrlist, histogram
!
% hmode
!
>
>> default hmode ['=']
>> default hmode ['='] data
>> default hmode ['='] time
>
>The hmode default is used by the histogram command to determine
>whether data value or delta time information will be histogrammed.
>The initial value is 'data'.
>
>Examples:
>     > default hmode=time    ! histogram delta time data
>
>See also:
>     default, attrlist, histogram
!
% hprecision
!
>
>> default hprecision ['=']
>> default hprecision ['='] auto
>> default hprecision ['='] <number>
>
>The hprecision default is used by the histogram command to determine
>how many asterisks (*) to print out for each of its buckets.  The initial
>value of this attribute is 'auto' which will make use of the 'columns'
>attribute to produce a histogram which makes use of the full screen.
>
>The number specified is the number of references per asterisk.
>
>Examples:
>     > default hprecision=10   ! 10 refs per *
>
>See also:
>     default, attrlist, histogram
!
% hwidth
!
>
>> default hwidth ['=']
>> default hwidth ['='] auto
>> default hwidth ['='] <number>
>
>The hwidth attribute is used by the histogram to determine the width
>of each bucket.  The initial value of this attribute is 'auto' which
>will make use of the 'hbuckets' and 'limits' defaults to determine
>the number of buckets and their width.
>
>The number specified is the width of each bucket.
>
>Example:
>     > default hwidth = 10     ! each bucket contains 10 data values
>
>See also:
>     default, attrlist, histogram
!
% iecho
!
>
>> default iecho ['=']       ! inquires current setting
>> default iecho ['='] echo
>> default iecho ['='] noecho
>
>Controls the echoing of include files.  The initial setting is "noecho"
>unless the postprocessor was invoked with the -e option.
>
>See also:
>     default
!
% limits
!
>
>> default limits ['=']
>> default limits ['='] [<low_bound>] [',' <high_bound>]
>
><low_bound> ::= '^' | <number>
><high_bound> ::= '$' | <number>
>
>The limits default allows the user to restrict the range of data
>values considered by a command.  This default is initially set to ^,$
>which means all data values will be considered.
>
>It is possible to set only one of the limits.
>
>Examples:
>     > default limits ,60              ! set upper limit only to 60
>     > ... command ... {limits=20,$}   ! set both limits
>
>See also:
>     default, attrlist
!
% prompt
!
>
>> default prompt ['=']       ! inquires current setting - initially "> "
>> default prompt ['='] <double_quoted_string>
>
>For those who like to completely control their environment.....
>
>See also:
>     default
!
% sbase
!
>
>> default sbase ['=']         ! inquire current setting - initially decimal,
>                              ! signed, no leading characters, nonverbose
>> default sbase ['='] <basespec>
>
>Controls the output format used for the printing of subscripts.
>
>See also:
>     default, basespec
!
% tbase
!
>
>> default tbase ['=']         ! inquire current setting - initially decimal,
>                              ! signed, no leading characters, nonverbose
>> default tbase ['='] <basespec>
>
>Controls the output format used for the printing of time.
>
>See also:
>     default, basespec
!
!  ================
!    Other Topics
!  ================
!
% basics
!
>
>GPP Basics:
>
>gpp displays information obtained from trace data files produced by the
>simulator (*.d files).  Each invocation of gpp can read in one
>or more trace data files.  The files can be specified either on the
>program invocation command line, or as arguments to the 'load' command.
>
>The last trace file read determines the 'default' trace file,
>as well as the default time bounds.  If you choose to use gpp with
>more than one trace file per invocation, then you will have to
>change between files, which is done with the 'default file' command.
>
>Each file contains one or more 'monitors', which initially were
>created with a simulator (n2) 'trace' command.  Each monitor has a
>'tag' number, which identifies it.  Most commands require the
>specification of a monitor as a parameter.  This can be done with
>either the tag number, or the name of the structure which was the
>subject of the trace command in the simulator.
>
>You may want to run the 'list' command after reading in
>a file to see what monitors it contains.
>
>Most commands operate over a particular simulation time range, which
>can either be explicitly set on the command line, or default to the
>'default bounds' values.  Note that initially the the default time
>bounds are set to the minimum and maximum time values within that file.
>You can change them with the 'default' command if desired.
>
>To make it easier to use, gpp (just like the simulator) allows
>include files, output redirection, and scripting.  These
>features let you save gpp output into files, as well as use gpp
>in a 'batch' mode of operation.
>
>See the 'monspec' and 'commands' topics for more information,
>as well as other relevant gpp help text.
>
!
% basespec
!
>
>> default base <basespec>
>> default sbase <basespec>
>
>A basespec consists of 1 to 4 letters without embedded spaces.
>The letters may be selected from the following groups:
>
>Base indicator:
>     'b' or 'B'   Binary
>     'o' or 'O'   Octal
>     'd' or 'D'   Decimal
>     'h' or 'H'   Hexadecimal
>     'x' or 'X'   Hexadecimal
>
>Sign indicator:
>     'u' or 'U'   Treat as unsigned.
>     's' or 'S'   Treat as signed; If the value is positive, handle normally;
>                    if the value is negative, show a "-" followed by the 
>                    2's-complement value.
>
>Zero indicator:
>     'z' or 'Z'   Leading zeros are printed.
>     'l' or 'L'   Left justify with leading zeros suppressed.
>     'r' or 'R'   Right justify with leading zeros suppressed.
>
>Prefix indicator:
>     'v' or 'V'   Verbose - a leading "0x", "0d", etc is printed
>     'n' or 'N'   Naked - the prefix is omitted
>
>At most one letter from each group is provided (in any order).  If any of the
>groups is omitted, the meaning is "no change" -- typically no change from the
>current or default setting of that particular designator.
>
>The sign indicator is sometimes used to control whether data is interpreted
>as signed or unsigned 2's-complement values in internal gpp computations.
>
>See also:
>     base, sbase, tbase, default, attrlist
!
% shell
!
>
>'#' < host command line>
>
>On hosts which support subinstances of command interpreters, the command 
>passes the remainder of the line to a host command interpreter program for
>execution.
>
>Examples:
>     > # date
>     > # edit joe.isp
>
>The commands 'date' and 'edit joe.isp' are executed.  To determine if this
>feature is present in your implementation, execute the postprocessor with the
>'-v' option.  This will display status information including whether or not
>shell escapes are supported.
!
% #
!
>
>See 'shell'.
!
% numbers
!
>
>This section describes entering numbers to the post processor.  Numbers can 
>be entered in one of 4 different bases.  Each base has a two-character 
>prefix, which is:
>
>     0b    binary
>     0o    octal
>     0d    decimal
>     0h    hexadecimal
>     0x    hexadecimal
>
>The base character can be either an upper or lower case character.  The 
>characters following the base prefix define the number.  Each character must 
>be from the allowable set of characters for the given base.  For example, 
>binary numbers must be composed of either '0' or '1' characters, while 
>hexadecimal number can be composed of '0' to '9' and 'a' to 'f' (or 'A' to 
>'F').
>
>To simplify entering numbers, numbers beginning with a leading zero (but not 
>followed by a base specification character) are octal numbers, and numbers 
>beginning with the characters '1' to '9' are decimal.  Here are some correct 
>numbers:
>
>     1234           decimal
>     0d1234         decimal
>     0b01001111     binary
>     01234          octal
>     0b1234         octal
>     0xAbaB         hexadecimal
>
>When a number is parsed, the 'width' of the number is determined using 
>2's-complement rules.  The width is important when the number interacts with 
>structures of a different size.
>
>If a number is prefaced with a minus sign (-), it implies a 'negative' 
>number.  Syntactically, the minus sign must touch the number, with no white 
>space between them.
!
% commands
!
>
>Command names and other keywords can be abbreviated to the fewest number of 
>characters that make the name unique.  These reserved words are maintained in 
>several internal lists, so the definition of unique is dependent upon the 
>other words on the same list.  When an ambiguous keyword (matches more than 
>one keyword) is specified, the postprocessor treats it as if there were no 
>matches.
>
>In addition, every command can be followed by an attribute list enclosed in 
>curly braces.  The attributes specified there take effect for the rest of the 
>command (however, they may be overridden by argument attribute lists).
>
>See also:
>     attrlist
!
% endot
!
% zycad
!
!
% comments
!
>
>> ! This is a comment
>> files ! Comments may trail commands
>
>Any characters on a command line after the "!" character are ignored
>by the command line parser.
!
% restrictions
!
>
>The current version of gpp does not report some univariate statistics on 
>structures which are wider than the host machine word width (typically 32 
>bits).
>
>The statistics, histogram, and utilization commands currently do not support 
>structures which are memories or state arrays.
!
% monspec
!
>
><monitor_spec> ::= (<id> | <string> | <number) ['{'<attribute_list>'}']
>
>A monitor specification describes a monitor in the trace file database.  The 
>monitor can be identified by its name (<id> or <string>), or by its tag 
>number (<number>).  The optional attribute list, which must be enclosed in 
>curly braces, can specify additional information which will be used when 
>processing this argument.
>
>Since there may be more than one monitor on a named structure in a given
>trace file, the monitor tag number, along with its corresponding file index,
>is the combination which uniquely determines a monitor in the postprocessor
>environment.
>
>Any attribute may be specified in the trailing attribute list.  The behavior
>of different commands is modified by different attributes, but the 'file' 
>attribute has significance in all monitor specifications.
>
>Examples:
>     3 {file 2}                   ! Use monitor number 3 in the trace file 
>                                  !   with index 2 (specifies unique trace).
>     cpu:ir                       ! Use first monitor for cpu:ir in the 
>                                  !   default file.
>     5 {file=trace.d; base rud}   ! Look in the trace file data base for a 
>                                  !   file with the name 'trace.d' with the
>                                  !   lowest file index number.  From that 
>                                  !   file process the trace with tag number 
>                                  !   5.  When processing this trace, use the
>                                  !   new base specification.
>
>See also:
>     attrlist
!
% attrlist
!
>
><attribute_list> ::= <attribute_spec> [';' <attribute_list>]
><attribute_spec> ::= <keyword> ['='] [<value>]
>
>Attributes change the behavior of certain commands.  An attribute can
>be specified at three 'levels':  the global level (default attributes),
>the command level, and the argument level.
>
>Attributes are set at the global level using the 'default' command.
>
>Attributes are set at the command level by following the command keyword
>with an attribute list enclosed in curly braces.
>
>Attributes are usually set at the argument level by following the argument
>with an attribute list enclused in curly braces.
>
>An attribute list is a semi-colon separated list of attribute specifications.
>An attribute specification consists of and attribute keyword, followed by
>an optional equal sign, followed by an optional value.
>
>If the value field is not specified, and the attribute list is the argument
>of a default command, the current value of the attribute will be printed.
>
>The following attribute keywords are supported:
>
>  base         dtlimits       hprecision                  nticks
>  bounds       file           hwidth                      tbase
>  columns      hbuckets       iecho                       timechange
>  compare      hmode          limits                      timespec  
>
>Examples:
>     > default base                      ! inquire current setting
>     > default base ; tbase=             ! inquire two settings
>     > default base rd; hbuckets         ! set first, inquire second
>     > dump 3 {file=2; bounds 100,200}   ! add attributes to argument
>     > dump {file=2; bounds 100,200} 3   ! add attributes to command
>
>See also:
>     commands, monspec, filespec, and each of the above attribute keywords
>     for their specific syntax
!
% filespec
!
>
><file_spec> ::= (<id> | <string> | <number>) ['{'<attribute_list>'}']
>
>Files may be specified by name (<id> or <string>) or index (<number>).  If 
>specified by name, the complete name of the file must be used.  If the file 
>name contains special characters, it must be enclosed in double quotes.
>
>A file specification may contain an optional attribute list enclosed in curly 
>braces.  The attributes specified will alter the behavior of certain commands 
>when processing the specified file.
>
>If the file is specified using its name, the file with that name and the 
>lowest index number will be used.
>
>Examples:
>     > load "/usr/tmp/t"{bounds 100,200}   ! load file /usr/tmp/t.d into trace
>                                           !   file database.  Only store 
>                                           !   events which occur between time
>                                           !   100 and time 200
>     5                                     ! trace file with index 5
>     trace.d                               ! trace file named trace.d
>
>See also:
>     attrlist, load
!
% timerange
!
>
><time_range> ::= <time_bound> [',' <time_bound>]
><time_bound> ::= [('^' | '$') ['+' | '-']] <number>
>
>'^' denotes the lowest time value available; '$' denotes the highest time
>value available.  Note that these are not the lowest and highest possible
>time values but the lowest and highest values actually present.
