Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perlmod / DiagList / 1.11 / man / man3 / DiagList.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 "DiagList 3"
.TH DiagList 3 "2003-04-25" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
DiagList \- perl module for parsing diag lists
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use DiagList;
.Ve
.PP
.Vb 2
\& my $dlist = DiagList->new('./master_diaglist');
\& my $group = $dlist->find_group('cmp_regr');
.Ve
.PP
.Vb 1
\& foreach my $buildtag ($group->build_tags) {
.Ve
.PP
.Vb 1
\&   my $buildargs = $dlist->build_args($buildtag);
.Ve
.PP
.Vb 4
\&   foreach my $diagname ($group->list_diags($buildtag)) {
\&     my $diag    = $group->find_diag($buildtag, $diagname);
\&     my $runargs = $diag->get_cmdline();
\&   }
.Ve
.PP
.Vb 1
\& }
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
.Vb 2
\&  This is a perl module for parsing diag lists.  It uses
\&  XML-like syntax to define regression arguments.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module exists to parse diaglists and return results in a usable
format.  The Synopsis section above describes common usage.  This is
an object module with no exported functions.  The top-level object is
of type DiagList.  Sub-objects are returned of type DiagList::Group
and DiagList::Diag.  The public interface of each is described below.
.Sh "DiagList Object"
.IX Subsection "DiagList Object"
This is the only type of object the user will create explicitly.
.IP "new($file, [$fh]) <class method>" 4
.IX Item "new($file, [$fh]) <class method>"
Parse the given diaglist file and return a new DiagList object.
Throws an exception if it cannot parse the file.  If an optional
second argument is provided, it is treated as a file handle to read
from.  It can be either an IO::File object or a bare file handle.  In
this case the first argument, \f(CW$file\fR, is used purely for reporting
errors.
.IP "\fIbuild_list()\fR" 4
.IX Item "build_list()"
Returns a list of the build tags that were seen in the file.
.IP "build_args($build_tag)" 4
.IX Item "build_args($build_tag)"
Returns the build arguments for the specified build tag.  Returns
undef if a build tag called \f(CW$build_tag\fR was not seen in the file.  The
build arguments are the ones specified in the group tag defintion.
The only processing done is that name=<...> is stripped out
completely and sys=<...> is replaced by \-sys=<...>.
.IP "\fIbuild_hash()\fR" 4
.IX Item "build_hash()"
Returns a reference to a hash where the keys are build tags and the
values are the build args.  Note that this is a reference into the
internal state of the object, so modifying this hash will modify the
DiagList object.
.IP "\fIgroup_list()\fR" 4
.IX Item "group_list()"
Returns a list of group names that were seen in the file.
.IP "find_group($groupname)" 4
.IX Item "find_group($groupname)"
Returns a DiagList::Group object for the specified \f(CW$groupname\fR.
Returns undef if no such \f(CW$groupname\fR was seen in the file.
.IP "\fIgroup_hash()\fR" 4
.IX Item "group_hash()"
Returns a reference to a hash where keys are group names and values
are DiagList::Group objects.  Note that this is a reference into the
internal state of the object, so modifying the hash will modify the
DiagList object.
.Sh "DiagList::Group Object"
.IX Subsection "DiagList::Group Object"
These objects are created by the DiagList object and can be returned
to the user via the DiagList methods find_group and group_hash (both
described above).  The DiagList::Group objects support the following
methods.
.IP "name([$name])" 4
.IX Item "name([$name])"
Accessor function for the group name.  If an argument \f(CW$name\fR is
provided, the name of the group is set to \f(CW$name\fR.  The name of the
group is returned, whether or not it has changed.  Changing the name
with this method is highly discouraged for user code, but it is
perfectly acceptable to call \fIname()\fR with no arugments to get the name.
.IP "\fIbuild_tags()\fR" 4
.IX Item "build_tags()"
Returns a list of build_tags that are applicable to this group.
.IP "list_diags($buildtag)" 4
.IX Item "list_diags($buildtag)"
Returns a list of diag names in this group that correspond to the
given \f(CW$buildtag\fR.
.ie n .IP "find_diag($buildtag, $diagname)" 4
.el .IP "find_diag($buildtag, \f(CW$diagname\fR)" 4
.IX Item "find_diag($buildtag, $diagname)"
Returns a DiagList::Diag object that corresponds the the given
\&\f(CW$diagname\fR and the provided \f(CW$buildtag\fR.  Returns undef if no such
\&\f(CW$buildtag\fR or no such \f(CW$diagname\fR was found.
.IP "diag_hash($buildtag)" 4
.IX Item "diag_hash($buildtag)"
Returns a reference to a hash where the keys are diag names and the
values are DiagList::Diag objects.  Note tha this is a reference into
the internal state of the object, so modifying the hash will modify
the object.
.Sh "DiagList::Diag Object"
.IX Subsection "DiagList::Diag Object"
DiagList::Diag objects represent the state associated with a diag.
They are returned by the DiagList::Group methods \fIfind_diag()\fR and
\&\fIdiag_hash()\fR.  DiagList::Diag objects support the following methods.
.IP "\fIget_alias()\fR" 4
.IX Item "get_alias()"
Returns the diag alias, as provided in the diaglist file.
.IP "\fIget_nametag()\fR" 4
.IX Item "get_nametag()"
Returns the diag nametag, as provided in the diaglist file.
.IP "\fIget_name()\fR" 4
.IX Item "get_name()"
Returns the diag name which is the diag alias with :<nametag>
appended.
.IP "\fIget_full_name()\fR" 4
.IX Item "get_full_name()"
Returns the full diag name with alias, nametag, and group, separated
by ':'.
.IP "\fIget_file()\fR" 4
.IX Item "get_file()"
Returns the first file mentioned in the diag line.
.IP "\fIget_owner()\fR" 4
.IX Item "get_owner()"
Get debug owner form diag list.
.IP "\fIget_cmdline()\fR" 4
.IX Item "get_cmdline()"
Returns the command-line for the diag.  This includes arguments
specified in the DiagList::Group object that contains this object,
followed by arguments specified on the diag command line.  If the
containing group happens to be a buildtag (i.e., has a
sys=<something>), the sys=<something> is stripped out
of the diag command\-line.
.IP "\fIget_cmd_argv()\fR" 4
.IX Item "get_cmd_argv()"
This is the same as get_cmdline, except that it processes the
command-line with a shell and returns a list that can be treated as an
argv list.  Using this instead of get_cmdline allows diaglist entries
to be written the same way they would be on the command\-line.
.Sh "Syntax of the Diaglist file"
.IX Subsection "Syntax of the Diaglist file"
The syntax of the Diaglist file is somewhat strange.  It makes the
most sense to describe how it evolved than to try to explain the
entire syntax all at once.
.PP
\fIDiag Lines\fR
.IX Subsection "Diag Lines"
.PP
A diag line is a line in the diaglist that specifies a diag.  Its syntax is:
.PP
.Vb 1
\& <alias> <args>
.Ve
.PP
Where <alias> is a name for the diag, and <args> are
arguments to \fBsims\fR used to run the diag.  For instance:
.PP
.Vb 1
\& mydiag  mydiag.s -max_cycle=300000
.Ve
.PP
creates a diag alias \*(L"mydiag\*(R", which \fBsims\fR will invoke as \*(L"mydiag.s
\&\-max_cycle=300000\*(R".  One argument is special, however.  If an argument
is "debugowner=<username>", that argument is removed from the
command-line before it is passed to \fBsims\fR.  The debugowner is
available to clients of the DiagList module via the \fIget_owner()\fR
function, but it is not part of the command line because there is
nothing \fBsims\fR to do with it at runtime.  It is useful, however, for
informing the \fBdiagstatus\fR database of who owns which diags.
.PP
\fIGroups\fR
.IX Subsection "Groups"
.PP
The main organizational structure in the diaglist is a group.  A group
defines a list of diags for a regression and arguments to use for all
diags in that regression.  The syntax for a group is an XML-like tag.
The definition can contain arguments.
.PP
For example:
.PP
.Vb 1
\&  <foo -foo1 -foo2>
.Ve
.PP
.Vb 2
\&     abc    abc.s -abc
\&     def    def.s -def
.Ve
.PP
.Vb 1
\&  </foo>
.Ve
.PP
This defines regression group named \*(L"foo\*(R".  The arguments for the
group are prepended to each diag command line.  \fBsims\fR uses
Getopt::Long to parse its arguments, so if conflicting options are
repeated on its command\-line, the later option takes precedence.  This
means that diag-line options override group options if they are in
conflict.  If group foo were run in \fBsims\fR, it would run a diag with
alias \*(L"abc\*(R" and arguments \*(L"\-foo1 \-foo2 abc.s \-abc\*(R" and an alias \*(L"def\*(R"
with arguments \*(L"\-foo1 \-foo2 def.s \-def\*(R".
.PP
Groups can be opened multiple times, and they may have different
arguments each time.  Arguments are only used in the diags contained
in that particular tag.  For example:
.PP
.Vb 1
\& <foo -foo1 -foo2>
.Ve
.PP
.Vb 2
\&     abc    abc.s -abc
\&     def    def.s -def
.Ve
.PP
.Vb 1
\& </foo>
.Ve
.PP
.Vb 1
\& <foo -foo3>
.Ve
.PP
.Vb 1
\&     ghi    ghi.s -ghi
.Ve
.PP
.Vb 1
\& </foo>
.Ve
.PP
This would run \*(L"abc\*(R" and \*(L"def\*(R" exactly the same as before.  The diag
\&\*(L"ghi\*(R" would be run with \*(L"\-foo3 ghi.s \-ghi\*(R" and would not include
\&\*(L"\-foo1 or \-foo2\*(R".
.PP
Group definitions may nest, but this does \fBnot\fR imply any
relationship between the groups.
.PP
.Vb 2
\&  <foo -foo1>
\&   <bar -bar1>
.Ve
.PP
.Vb 1
\&      abc  abc.s -abc
.Ve
.PP
.Vb 2
\&   </bar>
\&  </foo>
.Ve
.PP
This defines two different regressions, \*(L"foo\*(R" and \*(L"bar\*(R".  In
regression \*(L"foo\*(R", \*(L"abc\*(R" will have arguments \*(L"\-foo1 abc.s \-abc\*(R".  In
regression \*(L"bar\*(R", it will have arguments \*(L"\-bar1 abc.s \-abc\*(R".  There is
no notion of group \*(L"foo\*(R" containing group \*(L"bar\*(R" or anything like that.
They just happen to have some diag lines in common.
.PP
Note that this means that a diag alias by itself does not define a
unique test (diag plus arguments).  The alias/group combination is
necessary, but not sufficient, to make a diag unique.  More on that
later.
.PP
\fINesting tags\fR
.IX Subsection "Nesting tags"
.PP
One special tag, <runargs> specifies arguments to all enclosed
diags, regardless of their group.
.PP
.Vb 3
\&  <runargs -runrun>
\&    <foo -foo1>
\&     <bar -bar1>
.Ve
.PP
.Vb 1
\&        abc  abc.s -abc
.Ve
.PP
.Vb 3
\&     </bar>
\&    </foo>
\&  </runargs>
.Ve
.PP
This means that in group \*(L"foo\*(R", the diag \*(L"abc\*(R" will run as \*(L"\-runrun
\&\-foo1 abc.s \-abc\*(R" and in group \*(L"bar\*(R", it will be \*(L"\-runrun \-bar1 abc.s
\&\-abc\*(R".
.PP
You can nest <runargs> tags.  Inner tags will append to the
argument list so inner <runargs> will override outer tags if
any arguments are in conflict.  Please note that a <runargs>
tag does \fBnot\fR define a regression, so there is no group called
\&\*(L"runargs\*(R".
.PP
Another special tag that applies to all enclosed diags, regardless of
their group, is <debugowner>.  Just as described for the diag
line, <debugowner> does not affect the command line at all,
but it does provide information to the \fBdiagstatus\fR database about
who owns which diags.
.PP
.Vb 1
\&  <debugowner someuser>
.Ve
.PP
.Vb 1
\&  ...
.Ve
.PP
.Vb 1
\&  </debugowner>
.Ve
.PP
This is the same as having \*(L"debugowner=someuser\*(R" on every diag line in
its scope.  Note that if a diag line contains a \*(L"debugowner=...\*(R" and
it is inside a <debugowner> tag, the diag line will take
precedence.
.PP
\fISpecial Groups\fR
.IX Subsection "Special Groups"
.PP
There are two types of special groups, buildtags and nametags.  They
are syntacticaly just like any other groups, and they define
regressions just like any other groups.  They have special meanings
and restrictions, however.
.PP
Build Tags
.IX Subsection "Build Tags"
.PP
A buildtag is any group that has "sys=<sysname>" in its
argument list.  (Note that all \fBsims\fR options begin with '\-', so any
argument of the form "<name>=<value>" is an argument
to the diaglist parser).
.PP
A buildtag defines the model that should be built for the regression
and the \fBsims\fR options of how to build the model.
.PP
.Vb 1
\&  <build1 sys=cmp -arg1 -arg2>
.Ve
.PP
.Vb 1
\&  ...
.Ve
.PP
.Vb 1
\&  </build1>
.Ve
.PP
This creates a buildtag called \*(L"build1\*(R" that specifies that all diags
inside it should be run with the \fBsims\fR \*(L"cmp\*(R" model, which can be
built with \*(L"\-arg1 \-arg2\*(R".
.PP
Unlike other groups, buildtags do \fBnot\fR nest.  Each diag line must
appear in \fBexactly one\fR build tag.  All diaglines in all groups
inside the scope of the buildtag will be run on the specified model.
.PP
.Vb 7
\&  <build1 sys=cmp -arg1 -arg2>
\&   <foo -foo1>
\&    <bar -bar1>
\&      mydiag mydiag.s -diag1
\&    </bar>
\&   </foo>
\&  </build1>
.Ve
.PP
When you run regression \*(L"foo\*(R", it will build a cmp model with args
\&\*(L"\-arg1 \-arg2\*(R".  It will then run \*(L"mydiag\*(R" with arguments \*(L"\-foo1
mydiag.s \-diag1\*(R".  Similarly, if you ran regression \*(L"bar\*(R", it would
build the same cmp model and run \*(L"mydiag\*(R" with \*(L"\-bar1 mydiag.s
\&\-diag1\*(R".  Note that \*(L"\-arg1\*(R" and \*(L"\-arg2\*(R" are used at build time for
groups \*(L"foo\*(R" and \*(L"bar\*(R", but they do not appear on the diag
command-line during the run.
.PP
A build tag also defines a regression, so you could run a regression
\&\*(L"build1\*(R" with the above diaglist.  It would build with \*(L"\-arg1 \-arg2\*(R"
and would run \*(L"mydiag\*(R" with \*(L"\-arg1 \-arg2 mydiag.s \-diag1\*(R".  There is
no way for the diaglist parser to tell build-time arguments from
run-time arguments when a buildtag is used as a regression group.
Fortunately, \fBsims\fR will ignore run-time options at build time and
vice\-versa, so using buildtags as groups is perfectly legal.
.PP
Name Tags
.IX Subsection "Name Tags"
.PP
An ambiguity is possible with multiple groups that contain diags with the same alias.  For example:
.PP
.Vb 1
\&  <both>
.Ve
.PP
.Vb 5
\&   <foo>
\&     <runargs -foo1>
\&       mydiag  mydiag.s
\&     </runargs>
\&   </foo>
.Ve
.PP
.Vb 5
\&   <bar>
\&     <runargs -bar1>
\&       mydiag  mydiag.s
\&     </runargs>
\&   </bar>
.Ve
.PP
.Vb 1
\&  </both>
.Ve
.PP
Note that we use <runargs> tags instead of putting them in the
\&\*(L"foo\*(R" and \*(L"bar\*(R" regressions directly, since we want the \*(L"both\*(R" group
to run \*(L"mydiag\*(R" once with \*(L"\-foo1\*(R" and again with \*(L"\-bar1\*(R".  The problem
with the above diaglist is that both runs of \*(L"mydiag\*(R" have the same
alias/group combination when run in group \*(L"both\*(R".  Some other
identifier is needed to give each diag a unique name.
.PP
Nametags are used for this purpose.  A nametag is a group that has
"name=<name>" in its argument list.  The name is appended to
the alias do define a name that is unique within a group.  The
alias/nametag/group combination is enough to make a diag unique
overall.  As with buildtags, nametags do not nest, and each diag must
appear in \fBexactly one\fR nametag.  We can rewrite the above diaglist
as:
.PP
.Vb 1
\&  <both>
.Ve
.PP
.Vb 5
\&   <foo_group name=foo>
\&     <runargs -foo1>
\&       mydiag  mydiag.s
\&     </runargs>
\&   </foo>
.Ve
.PP
.Vb 5
\&   <bar_group name=bar>
\&     <runargs -bar1>
\&       mydiag  mydiag.s
\&     </runargs>
\&   </bar>
.Ve
.PP
.Vb 1
\&  </both>
.Ve
.PP
Group \*(L"foo_group\*(R" contains the diag \*(L"mydiag:foo\*(R" with args \*(L"\-foo1
mydiag.s\*(R".  Group \*(L"bar_group\*(R" contains the diag \*(L"mydiag:bar\*(R" with args
\&\*(L"\-bar1 mydiag.s\*(R".  Group \*(L"both\*(R" contains two diags: \*(L"mydiag:foo\*(R" with
\&\*(L"\-foo1 mydiag.s\*(R" and \*(L"mydiag:bar\*(R" with args \*(L"\-bar1 mydiag.s\*(R".
.PP
When \fBsims\fR creates a directory to run a directory, it uses
<alias>:<nametag>:<group> to get a unique
directory name.  In contexts where only a single group is relevant,
then <alias>:<nametag> is sufficent to name a diag.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIsims\fR\|(1).