Bundles
This program checks that the signal behaviour shown in the .out trace file
produced by aTimeMill® simulation meets the constraints of an asynchronous 4 phase
bundled data protocol. In addition to the basic bundling constraints
this program checks set up and hold times with respect to the
handshake signals and also checks for clean transitions on the
handshake signals.
The program has been designed to examine the worst cases for the set
up and hold times. It also produces statistics about the timing of the
active period (between req and ack) for each bundle, and about the
minimum set up and hold times for each bundle, allowing the
identification and reduction of overly conservative matching delays.
The data bundles, the active edges of the handshake signals and the set up and
hold times are defined in a .check file that may be shared with other
checking programs. These .check files may be built up into a hierarchy
matching the hierarchy of the design.
To avoid spurious errors during the initialisation of the simulation,
it is possible to set a time before which all errors are ignored.
Contents
bundles [-layout] unitname [checkfile]
- -layout
- This flag specifies that the trace file was generated from a
layout. The default is to assume a trace generated from a
schematic. This flag selects the appropriate way of building
hierarchical signal names to match those in the trace files.
- unitname
- The name of the design unit you wish to process. (This may include
the .out extension for the trace file). This unitname is used to
derive the names of the input files. To allow the bundle checking of
traces bigger than can be stored in the available disc space, this
program has the ability to accept the trace input on stdin, thereby
allowing a direct pipe connection between the simulator and the
bundle checker. To specify the use of input on stdin, the unitname
must be given as `stdin' and the checkfile must be specified
explicitly.
- checkfile
- The name of the file that defines the data bundles. The '.check'
extension may be included or omitted. If this optional argument is
not included, the check file name is derived from the unitname.
- unitname.out
- The trace file produced by TimeMill®. The program is designed
to be robust in the face of truncated trace files, allowing the
check to be run on traces that have been aborted before completion
of the simulation. By providing partial results from such incomplete runs a lot of time can be saved by avoiding having to
re-execute large simulations.
- unitname.check
- The file defining the data bundles, handshake signals, active edges,
set up and hold times, ignored period and check file hierarchy. The
format of this file is described later.
Output is written to stdout. Errors are logged on stderr.
The output produced by the tool should be self explanatory, but is
very verbose. The test.results file is an
example of this output. The results may be divided into 3 parts:
- The Header This describes the way in which the
analysis has been set up, listing the files accessed, the times at
which those files were created, any default values used, the number
of bundles defined, the hierarchical prefixes and any ignored
period. Indentation is used to indicate the use of hierarchical
.check files.
- The Errors This section includes a separate
message for every error on every signal. These errors appear in the
order in which they were detected. Further details of the types of
error and the ways in which they are measured are given later.
- The Statistics This data starts with a summary
of the number of each type of error detected. It then provides
information about each bundle, detailing the number of cycles and
the maximum, minimum and average active times, where the active time
is defined at the time between req and ack (see diagram). These activity statistics are
sorted to present the bundle with the largest average active time at
the top of the list. Examination of this information may indicate
bottlenecks in the asynchronous pipelines.
In order to preserve the formatting and keep
the table easy to read, long signal names will be truncated. This is
done by removing characters from the left hand end of the name and
adding the prefix '+++' to indicate that a truncation has occurred.
The activity time statistics are followed by lists of the minimum
set up and hold times for each bundle. Although it is essential for
the correct operation of the circuit that set up and hold times are
not violated, it is desirable from the point of view of performance
that the excess delays beyond these required set up and hold times
should be as small as possible, since they represent wasted time
during which no useful work can be performed. The production of the
minimum set up and hold time statistics makes it possible to
identify and optimise any overly conservative delay paths. Note that
if there are violations, these set up and hold times may be negative.
The raw output of this tool may be processed into a rather more
readable form using the summarisebundles utility.
Examples of the input files and the output they produce are available
on line:
- test.out (15k)
- This is an artificially created trace file in the same format that
TimeMill® produces. This has been
designed to test most branches of the bundles program. It is heavily
annotated to explain the tests that it is performing and the
expected results.
- test.check (3.5k)
- An example of a .check file with definitions of bundles etc. This
is a top level file, which calls another subordinate .check file.
- testinclude.check (3.5k)
- A further example of a .check file. This one is subordinate to
test.check in the design hierarchy.
- test.results (8k)
- The results produced from test.out and test.check.
The file format used to select the signals to be monitored is designed
so that the same data file may be used by a variety of programs: the
bundle checker only pays attention to information between the lines
"start bundle" and "stop bundle" (or the end of the file). Anything
before or after these lines is totally ignored. The elements that may
appear in the bundles definition are:
- Blank lines and comments
- Comments are introduced by a semi-colon as the first character on
a line. Comments and blank lines are ignored.
- Definitions of default set up and hold times
- The use of default values makes it simple to set up and change
the latch characteristics for all bundles, on the assumption that
the characteristics for all latches will be the same. If the
defaults are not suitable, more precise definitions of the set up
and hold times for the relevant latches may be included in the
bundles definitions lines. The default definition lines take the
form:
def sut = 1
def ht = 0
The times are in units of nanoseconds. These defaults only apply to
bundles declared in the same file. The values take effect
from the point of the declaration until the end of the file unless
they are overwritten by a further default definition in the same
file. The scope of these definitions is important in the use of
hierarchical check files, since it means that each level in the
hierarchy may have different defaults. Until a default value is set in
the current file, the default values from the level above it in the
hierarchy will be used. At the very top level program defined default
values (sut = 1ns, ht = 0.5ns) are used until more explicit definitions
are given.
- Bundle definitions
- Each of these lines declares a single bundle. The lines take the
form of a list of fields separated by white space:
req ack reqedge ackedge sut ht bundle
- req and ack
- The names of the request and acknowledge signals for this
bundle. The syntax for these names is given later.
- reqedge and ackedge
- The active edges of the request and acknowledge signals. These
two signals do not need to be active on the same edge. These fields
may contain:
- "r" for a rising edge.
- "f" for a falling edge.
- sut and ht
- The set up and hold times for this bundle. These fields may
contain:
- A number which is used as a time (in nanoseconds).
- "*" which indicates that the currently active default
values should be used.
- "-" which indicates a don't care condition, in which
case the appropriate check is not performed on this bundle.
- bundle
- The data signals in this bundle. This is a space separated list
of bus and signal names. The syntax of these names is given later.
- Continuation lines
- These declare further data signals to be included in the preceding
bundle declaration. They are provided to improve formatting by
avoiding the need for very wide declaration lines. Continuation
lines consist of a "+" as the first character on a line,
followed by some whitespace followed by a space separated list of
signal and bus names. There may be more than one continuation line
for each bundle. For example
req2 ack2 f r * 3 data2[10:8]
;now some continuation lines
+ data2[7:3]
+ data2[1:0]
- Hierarchy declaration
- This declaration is used to set up a hierarchy of .check files, as
described later. The syntax is:
include filename prefix
At the point at which this line is encountered, the check file
filename.check is opened and processed, including any
further check files that it may include. Once the included file has
been exhausted examination of the current file continues after this
line.
The prefix given in the hierarchy declaration is prepended to all
signal names used in the included file (including any other levels
of hierarchy).
- Prefix declaration
- This declaration specifies the prefix that is to be applied to any
signal names in the rest of the current .check file. This over-rides
any existing hierarchical prefixes and any set by previous prefix
commands. It will also affect the generation of hierarchical
prefixes for any files included below this one in the hierarchy, but
will not affect any files above it. The format is:
prefix = aPrefix
- Ignored time declaration
- This declaration makes it possible to avoid spurious errors
arising during start up and circuit initialisation by ignoring a set
period at the start of the simulation. The format is:
ignoreuntil 1000
Where the number is the time in nanoseconds at which error
monitoring will begin. This mechanism is not ideal
since the same period will apply to all traces run under the same
checkfile, but it is better than nothing. Ignore periods may be
declared in more than one of the files in the checkfile hierarchy,
in which case the the longest of the ignored periods is used.
- Alias declarations
- This declaration is used to circumvent the fact that a signal may
have several aliases at different levels in the design hierarchy and
although only one of those aliases will appear in any given trace
file, if the same .check file is to be included into several levels
in the hierarchy, the different traces may make use of different
names. The syntax is:
alias signal_name alias_name
The use of aliases is described in more detail in the section on the
syntax of signal names.
The .check files that declare bundles may be arranged hierarchically
to match the hierarchical design style that is normally
employed. There should be one check file for each of the hierarchical
design units. This allows independent testing of the units in the
hierarchy, gradually building up to a test of the whole design. A
typical design flow would involve the design and testing of the lowest
level units, then the grouping of theses together to form a number of
higher level units which could then be tested, followed by further
grouping and testing until the design is complete. This form of
development and testing is supported by the include directive
that may be used in .check files. This allows the inclusion of the
check file for a lower level in the hierarchy.
As the hierarchy is built up, signal names are generated by adding the
hierarchical unit names to the front of the signal name; for example
"unit2.unit1.unit0.signal". At each level the .check file should use
the signal name as it would be used in a design unit at the corresponding
level in the hierarchy. As the checkfile is included into a larger
hierarchy, the full signal names are generated by prepending the
prefixes given as part of the include statement. Note that a .check
file can easily refer to signals at a lower level in the hierarchy
(using a suitably prefixed signal name), but there are also facilities
for referencing signals at higher levels, as described in the next
section.
When dealing with hierarchical .check files the scoping rules should
be understood. These apply to the default set up and hold times and to
any aliases. These values are in scope from the point at which they are
declared to the end of the file in which they are declared except that
they are out of scope within any included files. On return from any
included files any of these values return to scope with the values
that they had before the include.
As described in the previous section, signal names may be built up
hierarchically by adding prefixes as included check files are
scanned. Under some circumstances greater control is required over the
way that signal names are built up due to the way that aliases may be
introduced for signals that cross the boundaries between hierarchical
units. This section describes how this may be done and also introduces
the shorthand used for bus names.
Firstly, in those places where buses may be used, a series of signals
with contiguous indices may be specified with the single description:
busname[max_index:min_index]
The signal and bus names should be given as they would appear in the
corresponding level of the design hierarchy, including any
hierarchical prefixes. Note that in traces derived from schematics,
additional 'x's are included as part of the hierarchical separators,
for example, level1.level2.name would appear in the trace as
xlevel1.xlevel2.name. The additional characters should not be included
in the .check file, they will be added if necessary according to the
setting of the -layout command line flag, but be aware that, if a schematic trace is
used, the extra characters will be included in the output and error
messages.
Where signals are contained entirely within a single hierarchical module, the
prefix operation works perfectly, but complications arise where a
signal crosses hierarchical boundaries since aliases may be
introduced . For example consider an address
bus that is used within two design units and linked to them at the
next level up in the hierarchy. Within unit1 and its check file the
bus may be known as addr[31:0], and that will appear in the trace file
and may be used in bundle checking. Similarly within the second unit,
it may also be known as addr[31:0] and that will work
correctly. However, when the units are linked together and a
corresponding .check file is established and the prefixes are added,
there will now be 2 names for the same bus: unit1.addr[31:0] and
unit2.addr[31:0]. Furthermore, because this same bus appears at the
higher level in the design, where it is also known as addr[31:0],
neither of these extended names will appear in the trace file, where
the highest level name will be used. To avoid the problems that this
introduces, signal names may be prepended by one or more '^'
characters, each of which indicates that one level of the hierarchical
structure should be removed from the signal name. If there
are not enough hierarchical sections in the name to match the number
of circumflexes, as many as possible are removed and the remainder is
used as the signal name. For example:
^^addr
means a remove up to 2 levels of prefix from a signal name ending with
addr, so level2.level1.level0.addr would be converted to level0.addr,
while level0.addr would be converted to addr. Using this technique,
.check files may be created that may be used at all stages in the
hierarchical design without need for modification. In the example
given above, the unit1 and unit2 check files would specify the bus as
^addr[31:0], which would allow units 1 and 2 to be checked
independently and included into the check for the next level in the
hierarchy.
The ^ syntax deals with one special, though common, case of aliasing,
where the different design units use the same name for the signals and
it is only the different levels in the hierarchy that need to be taken
into account. However, the bundles tool has a more general mechanism
for dealing with aliases that will cope with the more general case of
signals whose names change totally between units. This makes use of a
list of aliases generated from the alias declarations in the .check
file. Note the the scope of an alias declaration is from the point at
which it is declared to the end of that .check file.
When a signal or bus name is encountered either as a handshake signal
or a data signal in one of the bus declarations, the following
operations are performed:
- Any bus declarations are split out into lists of individual
signals, and the remaining stages are applied to those individual
signals.
- Any prefixes arising from the hierarchy of check files are
accumulated and added to the front of the signal name.
- Hierarchical names are adjusted using the '^' mechanism if
required.
- If the trace was generated from a schematic, extra 'x' characters
are added to the signal name as required.
- The signal name is looked up in the .out trace file. If it is not
found, the next alias for the original signal name is looked up. If
there is another alias it is taken as the signal name and the operation
jumps back to step 2.
Note that aliases are found on the basis of the name of the signal as
it appears in the check file (including any ^ prefix adjusters).
There may be many aliases for each signal and those aliases may
include prefix adjusters. Also note that aliases are defined on the basis of
individual signals : to declare an alias for an entire bus you must
declare individual aliases for each signal in the bus. This approach
can be long winded, but it does allow for mapping bus signals to
independently named signals or to slices of different buses at
different levels in the hierarchy. An example alias declaration might
be:
alias ^^addr[0] ^pc[2]
alias ^^addr[0] ^^^offset
These are the error checks performed by the tool:
- Bad req or bad ack
- A bad transition on a handshake signal. For example when a handshake
signal goes from 1 to undefined back to 1 instead of making the clean
transition 1-u-0.
- Bad data
- This occurs if a bundled data signal is found to be undefined when req
starts to become active (i.e. when req changes from a defined state to
the undefined state at the start of an active edge.).
- Constraint Violation
- This happens when a bundled data signal changes during the period
between req becoming active and ack becoming active. To be precise,
constraint violations are checked from start of an active edge on req
to the end of the active edge on ack.
- Set up time violation
- When a data signal change is too close to the active edge of the
associated req signal, a set up time violation is recorded. The set up
time is measured from the end of a transition on a data signal to the
start of the active edge on the req signal.
- Hold time violation
- If a data signal is not held steady long enough after the active edge
of the associated ack signal a hold time violation is
flagged. The hold time is calculated from the end of the active edge
on the ack signal to the start of an edge on the data signal.
The bundling analysis is performed in the following way:
- For each clean active edge on a req signal, the current
time is recorded for later use in constraint checking. In addition
all data signals are checked to ensure that they are in a defined
state and have been stable long enough to avoid a set up time violation.
- For each clean active edge on an ack signal, the last changed
times for each of the data signals is checked to ensure that none of
them show a constraint violation by having changed since the last
req. In addition the time at which the ack signal changed is
recorded for use in hold time checks.
- For each transition on each data line, the hold time relative to
the last ack signal is checked and the current time is recorded for use
in constraint at set up time checks.
Due to the way in which the bundle analysis is performed, the program
may display peculiar behaviour in a few circumstances:
- If req and ack signals are not matched a variety of error
messages may be produced which are not entirely correct. For
example, if the ack signal goes through more than one active edge
for each active edge on req, constraint errors will be flagged for all
data signals that have changed before the last of the ack edges,
even though they may not have changed until after the first
ack. This is regarded as a feature rather than a bug, since the
provision of multiple acks is a dubious practice.
- Due to the fact that all signal changes within a single time step
are reported in the trace file in numerical order of the node
number, it is possible that some data signals will be observed to
change before a req or ack signal, while others will be observed to
change after this handshake signal despite the fact that they all
change at the same time step. The upshot is that depending on the
numeric node number, some of these changes may be reported as
constraint violations while others appear as hold time
violations. It is not possible to avoid this without a considerable
performance penalty, so that has not been attempted. Instead, the
behaviour of the program ensures that some form of error is
reported, though any signals changing at the same time as a
handshake signal may not be reported in the expected error category.
- In some cases where there are multiple occurrences of the same
error on the same data signal in the same req/ack cycle, only one
error may be reported. For example, constraint violations are
detected when an ack is received by checking the time at which the data
signals last changed against the time at which the req became
active. Consequently, where a data signal changes several times between the
request and the acknowledge, only the change closest to the ack will
be reported; the other transitions will have been masked by the most
recent one.
- Under some circumstances, it is possible for one type of error to
mask another. For example, there may be a set up violation on a data
signal, but if that data signal changes again at the same instant
that the req changes, it is possible for the set up time violation
to be masked by the later change which may be reported as a
constraint violation. Care has been taken to ensure that even though
one type of error may be masked by another under these boundary
conditions, some form of error message will be produced. If the
masking error is fixed, the masked error will appear on a later run
of the bundle checker. Note that although some form of error is
guaranteed to be shown in the output of the bundle checker itself,
that masking error report may be discarded by some of the higher
levels of summarisation that may be applied to the output, in favour
of what appears to be a worse violation. However, even at these
higher levels of summarisation, if the worst violations are fixed,
less significant errors that had been masked will be revealed by a
further run of the bundle checker, so it is advisable to iterate
through the modify design, run simulation, perform bundle checks
cycle until there are no more errors.
At the moment this tool will only deal with four-phase handshake
signalling. It would be simple to include two-phase signalling (in
which both edges of the handshake signals are active) into both the
operation of the program and the syntax of the check files. However,
the need to check extra cases for each handshake signal would reduce
the performance slightly, so this function has been omitted for the
moment.
It is sometime desirable to obtain information such as that in the
activity statistics about the delay between two signals that
are not handshake signals. This can be done by declaring a dummy
bundle: the signals of interest should be declared as the handshake
signals and the appropriate edges declared, set up and hold times
should be declared as "don't care" and a single constant signal such
as VCC should be declared as the data bundle. The required
information will then appear in the activity statistics at the end of
the bundle analysis.
Implementation Language
Perl release 5.001d or greater.
The copyright and any intellectual property rights associated with this
work are retained by the author and the University of Manchester, but
permission is granted to freely copy, distribute, modify and use this
software under certain conditions, as described in the Artistic Licence (with the deletion of
clause 8). This licence is obtained from the Perl distribution.
Source Code
Subject to the licensing arrangements described above, the source code may
be obtained from http://www.cs.man.ac.uk/amulet/projects/horn/bundles
TimeMill is a registered trademark of EPIC Design Technology
Inc, 2901 Tasman drive, Suite 212, Sata Clara, CA 95054.
This software was developed as part of the OMI HORN
project at the University
of Manchester Department of Computer Science, funded as part of
the European Union ESPRIT initiative (project number 7249).
Rhod Davies (rhod@cs.man.ac.uk)
This page last modified
Tue Apr 9 1996 10:44:48