Crystal is a program that analyzes the performance of VLSI circuits. Its input consists of a circuit description extracted from the mask layout by Spinifex. 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.

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 Spinifex to extract your circuits. I've added additional code to Crystal so that it can read the Thyme files output by Spinifex. You can ignore the stuff at the beginning of Section 5 of the tutorial about all the possible options to Mextra. Just use Spinifex to extract your chip. Once you have a Thyme file, use the Crystal command thyme instead of the build command. If you give Crystal the command thyme foo.thy, Crystal will read in the file foo.thy in Thyme format.

When reading in Thyme files, Crystal compares the name of each circuit definition with the names of transistors in its model tables. Any definition whose name matches, e.g. PETran or NDTran, is considered to be a transistor. Its contents are not examined or interpreted by Crystal, but the gate, source, and drain terminals are used to build the transistor structure for Crystal's use. If you use non-standard transistor names, you'll need to modify the information in Crystal's model tables to match.

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.

To run Crystal, first use the DF Tool to bringover /ivy/ousterhout/crystal/crystal.df. You only need to bringover the files with "public" access. Then type "run crystal" to the command tool. This will open a viewer with Crystal running in it. From here on, type commands as described in the manuals, except use the thyme command instead of build to read in files. 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).