190 lines
5.0 KiB
Groff
190 lines
5.0 KiB
Groff
'\"macro stdmacro
|
|
.TH ECADMIN 1
|
|
.SH NAME
|
|
\f3ecadmin\f1 \- configure and control the global event counters
|
|
.SH SYNOPSIS
|
|
\f3ecadmin\f1
|
|
[\f3\-aDlMrT\f1]
|
|
[\f3\-d\f1 event[,event...]]
|
|
[\f3\-e\f1 event[,event...]]
|
|
.SH DESCRIPTION
|
|
.B ecadmin
|
|
may be used on systems with MIPS R10000 or R12000 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.
|
|
.PP
|
|
The
|
|
.I event
|
|
arguments identify hardware-specific event counters.
|
|
These may be either integers or mnemonic, case-insensitive names.
|
|
In conjunction with the
|
|
.B \-e
|
|
option, a single
|
|
.I event
|
|
specification of
|
|
.B ?
|
|
(with appropriate shell escape) will cause
|
|
.B ecadmin
|
|
to list all known event counters, and then exit.
|
|
.PP
|
|
The normal usage would be to enable global event counters with
|
|
.B ecadmin
|
|
and then to monitor the event counters with
|
|
.BR ecstats (1)
|
|
or the Performance Co-Pilot tools.
|
|
.PP
|
|
The options to
|
|
.I ecadmin
|
|
are as follows;
|
|
.PP
|
|
.TP 5
|
|
\f3\-a\f1
|
|
Enable \f3all\f1 event counters; this is an abbreviation for
|
|
using
|
|
.B \-e
|
|
with all of the possible
|
|
.I event
|
|
counters enumerated, or
|
|
.B \-e
|
|
.BR *
|
|
(with appropriate shell escape).
|
|
.TP 5
|
|
\f3\-D\f1
|
|
Turn on diagnostic output associated with the control operations.
|
|
.TP 5
|
|
\f3\-d\f1
|
|
Disable event counting for the nominated
|
|
.I event
|
|
counters.
|
|
.TP 5
|
|
\f3\-e\f1
|
|
Enable event counting for the nominated
|
|
.I event
|
|
counters.
|
|
.TP 5
|
|
\f3\-l\f1
|
|
List all event counters for which counting is currently enabled.
|
|
.TP 5
|
|
.B \-M
|
|
By default, event counting is not currently supported for systems
|
|
with a mixture or R10000 and R12000 processors. The
|
|
.B \-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.
|
|
.TP 5
|
|
\f3\-r\f1
|
|
Disable (and release the allocation for) all global event counters.
|
|
.TP 5
|
|
.B \-T
|
|
The
|
|
.B \-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
|
|
.B \-T
|
|
flag, as the reported event counter values maybe meaningless unless the
|
|
execution environment is very tightly controlled.
|
|
To have the desired effect,
|
|
.B \-T
|
|
may require the concurrent specification of the
|
|
.B \-M
|
|
flag.
|
|
.PP
|
|
If the operation is completed without errors,
|
|
.B ecadmin
|
|
has an exit status of zero.
|
|
.SH CAVEATS
|
|
The underlying hardware event counters are a finite resource, to be
|
|
shared amongst
|
|
multiple competing uses.
|
|
.PP
|
|
If there is any concurrent use of the process-based
|
|
event counters via either
|
|
.BR perfex (1)
|
|
or the counter-based SpeedShop profiling tools, then attempts
|
|
to manipulate the global event counters via
|
|
.B ecadmin
|
|
will not succeed.
|
|
Processes using the process-based event counters can be identified
|
|
with
|
|
.BR ecfind (1).
|
|
.PP
|
|
If global event counting is enabled via
|
|
.B ecadmin
|
|
then this will augment any concurrent use resulting from an
|
|
earlier use of
|
|
.BR ecadmin .
|
|
.PP
|
|
Once
|
|
.B any
|
|
global event counters have been enabled with
|
|
.BR ecadmin ,
|
|
then any future attempts to use either
|
|
.BR perfex (1)
|
|
or the counter-based SpeedShop profiling tools will
|
|
be unsuccessful, until
|
|
.B all
|
|
global event counters are released, either with
|
|
.B \-r
|
|
or by disabling all active counters via
|
|
.BR \-d .
|
|
.PP
|
|
For this reason, the user of
|
|
.B ecadmin
|
|
must be
|
|
.B root
|
|
to use any option other than
|
|
.B \-l
|
|
or
|
|
.BR "\-e ?".
|
|
.PP
|
|
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,
|
|
.B ecadmin
|
|
will adjust the description of event counter 14 accordingly.
|
|
.PP
|
|
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
|
|
.B \-T
|
|
flag is specified.
|
|
.PP
|
|
Identification of the types and revisions for all CPUs can be made using
|
|
the
|
|
.B \-v
|
|
flag to
|
|
.BR hinv (1),
|
|
or the
|
|
.B \-D
|
|
flag to
|
|
.BR ecadmin .
|
|
.SH SEE ALSO
|
|
.BR ecfind (1),
|
|
.BR ecstats (1),
|
|
.BR perfex (1),
|
|
.BR pminfo (1),
|
|
.BR speedshop (1)
|
|
and
|
|
.BR r10k_counters (5).
|
|
.PP
|
|
The specifications for the MIPS R10000 event counters may be found at
|
|
http://www.sgi.com/processors/r10k/performance.html
|