If you are using a color system, updates to this document are indicated like this. |
Whitespace includes spaces, tabs and newlines. No alphanumeric or punctuation symbol is whitespace.
A word is either a string that contains no
whitespace, or it is a string surrounded by (matched) braces. If a
word is enclosed in braces, then the value of that
word is the contents of those braces, and not the braces
themselves. To get braces round a whole word, those braces
should be enclosed within another set of braces; thus
{foo} has value foo and {{bar}}
has value {bar}.
A list is an (ordered) collection of words separated by whitespace. There may be leading and trailing whitespace as well. A list may be embedded as a word by enclosing it in a pair of braces.
A pair is a two-element list and a triple is a three-element list.
A key-value list is a list of even length where the first word in the list is a key, the second element is the value related to the first key, the third element is the second key, etc. It is possible to use lists for keys, even if it is not necessarily advisable.
An association list is a key-value list where each of the keys is unique.
A Layout Interchange Format file (or LIF file) consists of a header section and a body section. The header a (possibly zero) number of empty and comment lines, and the body is a pair (which may contain newlines within it, with the significance of those newlines depending upon the local context).
An empty line is any (header) line containing only whitespace. Empty header lines are ignored by the format reader, being indended to make the header easier to read.
A comment line is any (header) line where the first
non-whitespace character is a hash symbol (#). Comment
lines are ignored, being intended for people reading the file as
opposed to any computer system.
A header line consisting of a single form-feed (ASCII
0014) indicates that the rest of the file is part of the
body. This is not strictly necessary (the fact that the
body does not look like any header line is
sufficient to allow mechanised differentiation between the two
sections) but it is recommended, as it leads to a potentially more
useful human-readable output pwhen the file is printed.
Suggested comment lines include:
FILE-ID
VERSION
CREATOR
CREATED
GENERATOR
The first word of the body section should be
layout. The second word of the body
(which should be the rest of the body) is a key-value
list.
The value of a layout is a key-value list using keys from the following list. Each of the values in the layout is a node or wire definition, and consists of an association list which lists the properties of the devices in question.
arbitrate - Arbitrate node
| buffer - Buffer node
| duplicate - Duplicate node
| function - Function node (both
pre-defined and user-defined)
| hierarchy - Hierarchic node (sub-layouts)
| merge - Merge node
| sink - Sink node
| source - Source node (includes constants)
| split - Split node
| table - Table node
| tuple - Tuple node
| untuple - Untuple node
| wire - Wire (optional - for
defining properties of the wire)
| xin - External input port
| xout - External output port
| xctrl - External control port
| yellow - Yellow node
| |
Each of the key-value pairs in a node or wire's definition association list defines a parameter. These parameters can be subdivided into three groups.
The following parameters may be supplied (as part of the node's association list) to every one of the keys above with the exception of wires, for which they are not useful. Where a parameter is not supplied, it is assumed to be an empty list (unless that parameter is required, which results in an error being reported to the user if it is missing).
inputs {list} defines a list of wires that are connected to the input ports of the device. outputs and controls do the same (with the same argument format) for output and control ports of the device. If you give a wire name as the empty string, then no wire will actually be attached to the corresponding port.
at {xLocation yLocation direction} is a
required attribute, and defines where the device should be located (in
screen-units; the origin is arbitrary, and is thus recommended to be
0) and in what direction the device should be facing (any one of the
four principal compass directions: n s e w. Note that
the editor is configured to place south-facing nodes by default).
labels {label-association-list} attaches
labels to each of the ports on the device. The keys in the association
list should match the regexp: [ioc][0-9]+
where the initial letter indicates the group of ports that the
particular port is selected from, and the number indicates which port
of the group to label. The numbering starts from zero, and is separate
for each group on each device.
The parameter init {value} indicates the initial contents of the buffer. The buffer will be uninitialised if this parameter is not present.
The required parameter op
{operation} indicates the operation to be performed in the
node. It should be one of: + - * / % & | ^ ~ = < >
&& || ^^ ! (for a standard function - the symbols are
analogous to those used in C) or the string user which
indicates that this node contains a user-defined function
invokation, and that the parameters code
{code-body} and name
{function-name} defined the function.
When name is supplied but code is not supplied, name contains the name of a function in another module.
The main (required) parameter of a hierarchic node is the layout parameter, which allows the nesting of a layout within another (with the format being the same as for a top-level layout). External ports within the contained layout map onto the ports of the hierarchic node by the order of their declaration. This is the only order-dependant part of the definition of a layout's contents.
The title of the hierarchic node may optionally be supplied (if unsupplied, it defaults to Hierarchy) using the parameter title.
There are (probably) other useful parameters to pass here (like the port placement policy control). I'll write down what they are when I think of them and feel that they are reasonable to want under external control.
There is one required parameter: type
{type-code} which defines whether the source is a constant,
a random-value source, or whether it produces a stream of values
from a file (corresponding to values Constant,
Random and File respectively).
Constants additionally require the const {value} parameter to be present, and file-based sources require the file {filename} parameter.
There are two required parameters; name {table-name} and body {table-body}
These are (well, will be) similar to table nodes in their required parameters.
The wire sections are for configuring wires, but do not create any wires. Instead, wire creation is controlled by where there are wires connected to input, output and control ports.
Wires do not use any of the common parameters, instead having their own set:
The only required wire parameter. Used to bind the particular parameters in this block to a particular wire. Note that wires can have any word for a name, as long as it is unique within a particular layout.
A textual (human-readable) label for the wire.
The width of the wire, which may be a useful visual indicator. Note that widths greater than about 3 do not look very effective.
The Rainbow type of the wire. (Not currently supported)
# Some header lines
#
#CREATOR: fellowsd@cs.man.ac.uk
^L
layout {
source {
outputs {a1}
at {-40 -40 s}
type {Random}
}
sink {
inputs {spong} at {40 40 s}
}
hierarchy {
inputs {a1} outputs {spong} at {0 0 e}
layout {
xin {
outputs {b1} at {-40 -40 s}
}
buffer {
inputs {b1} outputs {b2} at {0 0 w}
init {42}
}
xout {
inputs {b2} at {-60 -10 n}
}
wire {
ident {b1}
label {Some kind of label}
}
}
}
wire {
ident {a1} label {foobar}
}
wire {
ident {spong} width {3}
}
}
$Log: LIF.html,v $ Revision 1.4 2000/05/15 09:29:02 fellowsd Updated to use standard style-sheet and justified paragraphs. Since there were no changes to the content, the content-change markings for the previous version are retained. Revision 1.3 1997/03/14 10:19:04 fellowsd Added more parts to LIF (as requested by Dan Oram) and added some support for navigation about the document (a contents list at the beginning) Revision 1.2 1997/02/17 14:28:30 fellowsd Added an example, and fixed a number of small problems which made the document unclear. Revision 1.1 1997/02/17 13:42:07 fellowsd Initial revision