ECADMIN(1)ECADMIN(1)NAMEecadmin - configure and control the global event counters
SYNOPSISecadmin [-aDlMrT] [-d event[,event...]] [-e event[,event...]]
DESCRIPTIONecadmin 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.
Page 1
ECADMIN(1)ECADMIN(1)
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 ALSOecfind(1), ecstats(1), perfex(1), pminfo(1), speedshop(1) and
r10k_counters(5).
Page 2
ECADMIN(1)ECADMIN(1)
The specifications for the MIPS R10000 event counters may be found at
http://www.sgi.com/processors/r10k/performance.html
Page 3
