Introduction
Crystal is a program that analyzes the performance of VLSI circuits. Its input consists of a circuit description extracted from the mask layout by Sinix. Users also supply a few lines of text to guide the analysis. Crystal then determines how long each clock phase must be and outputs information about the portions of the circuit that cause the worst delays. It works for both nMOS and CMOS circuits.
Crystal was originally written in C at Berkeley, but I've transliterated it to Cedar. The main documentation for the program exists on-line at Berkeley (in Unix format) and is available at PARC only in hardcopy form. There are two manuals. The first is entitled Using Crystal for Timing Analysis. It is a tutorial-style introduction to the program, designed to be easy to follow but not necessarily complete. The second manual is a Unix-style man page (man is the Unix program that prints out terse documentation for programs and subroutine packages). The man page is the final authority for reference information and is supposed to be complete, but it isn't necessarily easy to read unless you already know how things work. For the most part, the Xerox version of Crystal works exactly the same way as the Unix version. This memo describes those aspects of the Xerox version that are different.
Getting Circuits into Crystal
Crystal reads files in ".sim" format or in Thyme format. At Berkeley, we use a program called Mextra to extract circuits, and it creates ".sim" format files. At PARC, most likely you'll use Sinix to extract your circuits.
The input for Crystal is now provided by Core data structures. A program named Extract adds an entry to the ChipNDale P-menu, so that clicking this entry will extract your selected layout cell through Sinix, add the Capacitance information to the Core data by WriteCapa, and input the result into Crystal, leaving you in the same situation than after the build command of the reference manual.
The most difficult thing about getting information for Crystal has to do with transistor attributes (Sections 11, 12, and 14.5 of the tutorial). I've extended the format of Thyme files to allow for attributes. In the call to a transistor, after the connections and parameters, there is an optional list of attributes. The attributes are separated from the parameters by a semi-colon, and each attribute is of the form attName ← attValue. Both attName and attValue are symbols without any spaces or special characters. AttName is the name of the attribute, which must be Gate, Source, or Drain to select the terminal that the transistor applies to. AttValue is the value of the transistor, which should be the same as described in the tutorial. The first letters of attValue should be either Cr or Crystal to indicated that the attribute is intended for usage by Crystal (maybe this is unnecessary since Crystal is the only program that uses attributes, but maybe this will change someday)). The Crystal manuals say that the first letters should be Cr: or Crystal:, but Thyme does not permit colons in names so I've made the colons optional.
As an example of all of this, the following Thyme statement calls an nMOS transistor and gives it attributes on both its source and drain: "foo1: NETran[in, Gnd, X, Gnd | l ← 2, w ← 4; Source ← CrIn, Drain ← CrXYZ];"
To get one or more attributes in Spinifex output, attach a Chipndale property named $Crystal to the transistor instance. Spinifex will output the value of the $Crystal property in the transistor call after the semi-colon. Thus for the example of the previous paragraph you should create a property $Crystal with value "Source ← CrIn, Drain ← CrXYZ". The only problem with this approach is that it is hard to tell by looking at a transistor which is its source and which is its drain. For now you'll have to live with this problem; it would be nice if Chipndale and/or Spinifex were eventually extended to provide some indication of which is the source and which is the drain.
Running Crystal under Cedar
To run Crystal, first use the DF Tool to bringover [DATools]<DATools6.1>Crystal>Crystal.df. You only need to bringover the files with "public" access. Then type "Crystal" or "CDCrystal" to the command tool, depending of the input way you choose. This will open a viewer with Crystal running in it. From here on, type commands as described in the manuals, except use external calls to the Build module to load informations, either directly by program, or through the P-menu of ChipNDale. If you want to make multiple Crystal runs on different chips or on newer versions of the same chip, you'll have to destroy the Crystal viewer and run Crystal again (type "run -a crystal" to the command tool, or it won't let you run the same program a second time). Do not try to run multiple instances of Crystal, as all the variables describing the layout are GLOBAL ...
Commands description:
build cell,
Obsolete, now replaced by the input from ChipNDale through the command "Sinix to Crystal" of the P-menu.
bus node node ...,
Each argument is the name of a node to be marked as a bus (meaning it is highly capacitive).
capacitance pfs node node ...,
First argument gives capacitance value. Each successive argument is a node name, whose internal capacitance is changed to the given value.
check,
This procedure performs some simple static electrical checks. It shouldn't be invoked until after transistor flow has been determined. Warning messages are output about the following dubious features:
1. Nodes not attached to any transistors.
2. Nodes that can't be driven.
3. Nodes that don't drive anything.
4. Transistors that can't pass information.
5. Bidirectional transistors with no flow attributes.
6. Transistors between Vdd and Ground.
clear,
This command reinitializes timing and flag information in all of the nodes and transistors. Any information set by "set", "flow", and "delay" commands is cleared. The procedure also checks to be sure that certain flags, like inPath, haven't accidentally been left set.
critical [file] [index{m}],
This command reads arguments and prints out delay information. The command takes any of several arguments. If a file name is given, the critical path is written to that file. Otherwise output is to standard output. If a number is given, the number'th slowest path is printed out (otherwise, the slowest path is printed). If the number is followed by an "m" then only memory paths are considered.
delay node t1 t2,
This command invokes the delay calculations. There are three arguments. The first is the name of a node. The second is the time at which the node rises (-1 means that the node never rises) and the third is the time at which the node falls (-1 means that the node never falls).
dump file,
Dumps all the critical paths to the file contained in the first argument.
flow in/out/off/ignore/normal flow flow ...,
This command takes as arguments one of the keywords "in", "out", "off", "ignore", or "normal", and one or more flow names. Each of the named flows is marked according to the keyword. "In" means only let information flow in at this attribute, "out" means only let information flow out at this attribute, "ignore" means completely ignore this attribute, and "off" means don't let information flow at all through transistors labelled with this flow attribute. "Normal" means go back to the standard interpretation of the flow attribute.
help,
Prints out a list of the commands.
input node node ...,
Each argument is the name of a node to be marked as an input.
markdynamic node value node value ...,
This procedure scans the entire network structure, marking each transistor with the direction(s) that information can flow through the transistor. The marks are set with the flowFromSource and flowFromDrain flags. Flow can occur in a particular direction if there is an information source (chip input) on one side of the transistor, an information sink (output or transistor gate) on the other side, and no conflicting flow attribute. As an additional side effect, this routine turns fetNEnh transistors into fetNEnhP transistors or vice versa, depending on whether there is a load attached to the gate (no load means it's driven through a pass transistor).
model [name],
Used to see and set the current delay model. If there is an argument, it is the name of the new model to use.
options [name value] [name value] ...,
This command reads "name value" argument pairs and sets internal options. Some of the options require no values. If no names or values are given, then the current option settings are printed.
output node node ...,
Each argument is the name of a node to be marked as an output.
parameter,
Used to see and set the resistance and capacitance model parameters. The arguments contain a sequence of parameter names and values. If no names are given, then the values of all parameters are printed out.
prcapacitance [-t pfs] [node node ...],
Prints out capacitance information for nodes in the circuit. Args can contain a switch "-t threshold", where threshold specifies the minimum amount of capacitance a node must have to be printed (the default is 0). It can also contain a list of node names (default is "*"). All of the named nodes with greater than the specified amount of capacitance are printed. All switches in args must precede all node names.
precharged node node ...,
Each argument is the name of a node to be marked as precharged.
prfets [node node ...],
Prints out information about all fets whose gates attach to the nodes in the argument list. If no argument list is supplied, then absolutely all fets are printed.
prnodes [node node ...],
Each argument gives a node name. This command routine prints out information about every node that is given. If no arguments are given, then information is printed out about every node in the circuit.
prresistance [-t ohms] [node node ...],
Just like prcapacitance, except prints parasitic resistance values in ohms.
ratio [limit value] [limit value] ...,
This command checks the whole circuit to be sure that the nMOS ratio rules are obeyed. The command line may contain arguments of the form "limit value" to change the acceptable range for ratios.
recompute,
Recomputes delays through each of the critical paths, using the current delay model.
resistance ohms node node ...,
Not implemented.
set 0/1 node node ...,
Forces node to have the given value, and uses a simple logic simulator to propagate that information through the circuit as much as possible. If propAnyway is TRUE, then the simulation is invoked even if the node already had this value.
source file,
Reads in more commands from a command file.
statistics,
Calls various routines to print out statistics about what Crystal has done.
transistor
If there are no arguments, then all fields of all transistor types are printed. If there are arguments, the first one is the name of a transistor type, and subsequent arguments give <field value> pairs to set the individual fields for that transistor type. If the transistor type isn't currently in the table, a new type is created.
undump file,
Reads back in dumped critical paths from the file contained in the first argument. This is done in a very sloppy fashion: the nodes and transistors along the critical path have no relationship to actual nodes and transistors that might have been read from a design.
watch node node ...
Each argument is the name of a node to be marked as watched (watched nodes have their worst-case delays recorded in a separate list).