ecadmin(1)

NAME
     ecadmin - configure and control the global event counters

SYNOPSIS
     ecadmin [-aDlMrT] [-d event[,event...]]  [-e event[,event...]]

DESCRIPTION
     ecadmin may be used on systems with MIPS R1x000 processors to configure
     the global event counters maintained by IRIX using the underlying
     hardware event counter mechanisms.  The global event counters are
     maintained on a system-wide basis, aggregated over all processes and for
     all user and system mode execution.

     The event arguments identify hardware-specific event counters.  These may
     be either integers or mnemonic, case-insensitive names.  In conjunction
     with the -e option, a single event specification of ? (with appropriate
     shell escape) will cause ecadmin to list all known event counters, and
     then exit.

     The normal usage would be to enable global event counters with ecadmin
     and then to monitor the event counters with ecstats(1) or the Performance
     Co-Pilot tools.

     The options to ecadmin are as follows;

     -a   Enable all event counters; this is an abbreviation for using -e with
          all of the possible event counters enumerated, or -e * (with
          appropriate shell escape).

     -D   Turn on diagnostic output associated with the control operations.

     -d   Disable event counting for the nominated event counters.

     -e   Enable event counting for the nominated event counters.

     -l   List all event counters for which counting is currently enabled.

     -M   By default, event counting is not currently supported for systems
          with a mixture of R1x000 processors,  i.e. R10000 and R12000 or
          R10000 and R14000. The -M flag relaxes this restriction and allows
          control for the subset of the event counters that have the same
          interpretation across all processor types.  This option but should
          only be used in controlled execution environments where the
          integrity of the event counter values aggregated across processor
          types can be guaranteed.  Great care should be be exercised when
          interpreting the counter values under these circumstances.

     -r   Disable (and release the allocation for) all global event counters.

     -T   The -T (or ``trust me'') flag disables the semantic checks for
          combinations of event counters are normally not allowed on systems
          with mixtures of processors of different type and/or revision.
          Extreme care should be used with the -T flag, as the reported event
          counter values maybe meaningless unless the execution environment is
          very tightly controlled.  To have the desired effect, -T may require
          the concurrent specification of the -M flag.

     If the operation is completed without errors, ecadmin has an exit status
     of zero.

CAVEATS
     The underlying hardware event counters are a finite resource, to be
     shared amongst multiple competing uses.

     If there is any concurrent use of the process-based event counters via
     either perfex(1) or the counter-based SpeedShop profiling tools, then
     attempts to manipulate the global event counters via ecadmin will not
     succeed.  Processes using the process-based event counters can be
     identified with ecfind(1).

     If global event counting is enabled via ecadmin then this will augment
     any concurrent use resulting from an earlier use of ecadmin.

     Once any global event counters have been enabled with ecadmin, then any
     future attempts to use either perfex(1) or the counter-based SpeedShop
     profiling tools will be unsuccessful, until all global event counters are
     released, either with -r or by disabling all active counters via -d.

     For this reason, the user of ecadmin must be root to use any option other
     than -l or -e ?.

     Depending on the revision of the MIPS R10000 CPUs there is a difference
     in the interpretation of event counter 14 (``Virtual coherency
     condition'' for parts before revision 3.1 or ``ALU/FPU completion
     cycles'' for parts at revision 3.1 or later).  There are also some subtle
     differences in the semantics of some of the event counters.  In systems
     with a homogeneous deployment of R10000 CPUs at the same revision,
     ecadmin will adjust the description of event counter 14 accordingly.

     For systems with a mixed deployment of R10000 CPU revisions including
     some before 3.1 and some at or after 3.1, the interpretation of event
     counter 14 is undefined, and there may be some slight inaccuracies due to
     aggregation of counters with different semantics across all CPUs.  For
     this reason counter 14 may not be enabled on systems with mixed R10000
     reployments unless the -T flag is specified.

     Identification of the types and revisions for all CPUs can be made using
     the -v flag to hinv(1), or the -D flag to ecadmin.

SEE ALSO
     ecfind(1), ecstats(1), perfex(1), pminfo(1), speedshop(1) and
     r10k_counters(5).

     The specifications for the MIPS R10000 event counters may be found at
     http://www.sgi.com/processors/r10k/performance.html