Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perlmod / AnalyzeDiag / 1.07 / man / man3 / AnalyzeDiag.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "AnalyzeDiag 3"
.TH AnalyzeDiag 3 "2004-05-07" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
AnalyzeDiag \- Perl module for analyzing diag log files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use AnalyzeDiag;
.Ve
.PP
.Vb 2
\&  my $dir = '.';
\&  my $analyzer = AnalyzeDiag::Analyzer->new(dir => $dir);
.Ve
.PP
.Vb 7
\&  $analyzer->add_measurements
\&    (
\&     AnalyzeDiag::Measurement->new(name  => 'PointerChase',
\&                                   start => 'chase_start',
\&                                   end   => 'chase_end')
\&    );
\&  my %results = $analyzer->analyze();
.Ve
.PP
.Vb 1
\&  my @times = @{ $Results{PointerChase} };
.Ve
.PP
.Vb 1
\&  # Do something with times
.Ve
.PP
.Vb 1
\&  script_exit;
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
.Vb 3
\&  This module exports some functions that analyze diag log
\&  files.  It is intended to be used by diags that write
\&  their own post-processing scripts.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The AnalyzeDiag module contains two user-accessible classes:
AnalyzeDiag::Analyzer and AnalyzeDiag::Measurement.
.PP
The general usage is to create an AnalyzeDiag::Analyzer diag, given a
directory argument (see the example in the previous section).  You
then add AnalyzeDiag::Measurement objects to the analyzer.  Finally,
the call to the analyze method will produce a hash where the keys are
names of measurements and the values are arrays of times (in cycles)
for those measurements.
.PP
The AnalyzeDiag::Measurement object has a contructor called 'new'.
Its argument is a hash with keys 'name', 'start', and 'end'.  The name
field is used to identify the measurement.  The 'start' and 'end'
values define PCs at which the measurement should start and end.  They
may be virtual addresses (hex numbers without 0x) or labels.
.Sh "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
.IP "verbose( [$level] )" 4
.IX Item "verbose( [$level] )"
If \f(CW$level\fR is specified, set verbose level to that.  Returns verbosity
level.
.IP "script_say(@msg)" 4
.IX Item "script_say(@msg)"
Print the message always.
.IP "chat(@msg)" 4
.IX Item "chat(@msg)"
Print the message if verbose level >= 1.
.IP "debug(@msg)" 4
.IX Item "debug(@msg)"
Print the message if verbose level >= 2.
.IP "script_warning(@msg)" 4
.IX Item "script_warning(@msg)"
Print a warning message.
.IP "script_die(@msg)" 4
.IX Item "script_die(@msg)"
Print an error message, print a stack backtrace, and exit with status
2.
.ie n .IP "diag_ok( $bool\fR, \f(CW$name )" 4
.el .IP "diag_ok( \f(CW$bool\fR, \f(CW$name\fR )" 4
.IX Item "diag_ok( $bool, $name )"
Perform a test named '$name'.  Test passes if \f(CW$bool\fR evaluates to true
and fails otherwise.
.ie n .IP "diag_is($got, $expected\fR, \f(CW$name)" 4
.el .IP "diag_is($got, \f(CW$expected\fR, \f(CW$name\fR)" 4
.IX Item "diag_is($got, $expected, $name)"
Perform a test called '$name'.  Test passes if \f(CW$got\fR eq \f(CW$expected\fR (yes,
that is a string comparison) and fails otherwise.  This is a special
case of \f(CW$diag_ok\fR, but it produces much better output since the
function actually knows what is being compared.
.ie n .IP "diag_is_numeric($got, $expected\fR, \f(CW$name, [$tolerance])" 4
.el .IP "diag_is_numeric($got, \f(CW$expected\fR, \f(CW$name\fR, [$tolerance])" 4
.IX Item "diag_is_numeric($got, $expected, $name, [$tolerance])"
Same as diag_is except the comparison is numeric.  If \f(CW$tolerance\fR is
specified, the test passes if \f(CW$got\fR is within \f(CW$tolerance\fR of \f(CW$expected\fR.
.IP "script_exit" 4
.IX Item "script_exit"
Prints the exit status and exits with that status.  Exit status will
be 0 unless one or more tests have failed, in which case it will be 1.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1).