User Commands CRYSTAL(1) NAME crystal - VLSI timing analyzer SYNOPSIS crystal [file] DESCRIPTION Crystal is a semi-interactive program for analyzing the tim- ing characteristics of large integrated circuits. It esti- mates the speed of a circuit and prints out information about the critical paths. If file is specified, it is read in as though the build command (see below) had been invoked. Crystal processes commands from the standard input, one per line. Lines beginning with exclamation points are ignored. Unique abbreviations for commands are acceptable. The order of commands in the input is important. Commands are divided into seven groups, which should appear in the following order: Model commands These commands modify the circuit and timing models used by Crystal, and should appear before the circuit is read in. The model commands are model, parameter, and transistor. Circuit commands Used to input and describe the circuit being analyzed. The circuit commands are build, bus, capacitance, inputs, outputs, and resistance. Dynamic node command This group includes the single command markdynamic, used to find and mark the dynamic memory nodes in the circuit. Check commands Includes two commands, check, and ratio. These com- mands examine the circuit's structure for suspicious- looking electrical features. Setup commands There are three commands in this group, flow, precharged, predischarged, and set. These commands are used to restrict the analysis performed for a given clock phase. Delay command The delay command invokes the actual delay analysis. Miscellaneous commands These commands may be invoked at any time: alias, critical, dump, fillin, help, options, quit, SunOS 5.6 Last change: 1 User Commands CRYSTAL(1) prcapacitance, prfets, prresistance, source, statis- tics, undump, and watch. The only command outside these groups is the clear command, which resets information that was set by setup and delay commands. After clear, input may resume with anything except model commands. NODE NAMES Where node names are called for in commands, they can appear in any of several forms: [1] A simple node name. [2] A name of the form ``ab''. Crystal tries all names of the form ``acb'' where c ranges from x to y. To get a ``<'' character in the name, precede it with a backslash. [3] A name of the form ``*a''. Crystal searches the entire node table for names containing the string ``a''. Note: this kind of name specification is slow on large chips, since the entire table has to be searched. For example, on a sample 45000 transistor chip, 20 seconds of CPU time were used for each search. GRAPHICAL COMMAND FILES Several of the commands can be used with the -g argument to generate output for graphical display of information. At present, Crystal will generate command files for either Cae- sar, Magic, or Squid. To use Caesar command files, run Cae- sar on the chip and pick a view large enough to hold the whole chip (e.g. with the ``v'' short command). Then use the ``:source'' long command to read in the command file. The command files place labels and paint on the error layer to mark places, and also push boxes onto the stack so that you can step from one label to the next using the ``:pop- box'' long command. To use Magic command files, run Magic on the layout, place the cursor in the window containing the layout, and use the ``:source'' long command to read in the command file. A collection of feedback areas will be gener- ated. These can be examined using Magic's ``:feedback'' command. COMMANDS alias file Read in aliases from the information in file. Each line of the alias file is of the form ``= name name name ...'' where the first name is a node name that SunOS 5.6 Last change: 2 User Commands CRYSTAL(1) appears in the .sim file and each additional name is another name for the same node. After the alias com- mand, any of the names may be used to refer to a node. An alias file shouldn't be read in until after the .sim file has been read. build file Build a circuit description from the information in file, which must be in .sim format. This command is unnecessary if a file is specified on the shell command line, but is necessary if non-standard models are used. bus node node ... This command should only rarely be needed. Each of the nodes gets marked as a bus. When a node is a bus, Crystal assumes that delays through the node can be treated as separate stages to the node and from the node. Nodes with large capacitances are automatically considered to be busses: see the bus option below. capacitance pfs node node ... The parasitic capacitance value for each node is set to the given value. This overrides the capacitance esti- mate made from the mask layout. check Make a series of static electrical checks on the cir- cuit. This command prints out information about nodes with no transistors connected to them, nodes that are not driven, nodes that don't drive anything, transis- tors that are permanently forced off, transistors con- necting Vdd and GND, and transistors that are bidirec- tional but haven't been marked with a flow attribute. clear All information set by setup and delay commands is cleared, in preparation for an additional timing analy- sis. Information set by circuit commands isn't affected. After the clear command, input may contine with any commands except those in the model group. Information from the watch command is also cleared. ber][m][w] critical [file] [-g graphicsfile] [-s spicefile] [pathnum- Print out information about the critical paths. If pathnumber isn't specified, then the slowest path is printed. If it is specified, the pathnumber'th slowest path is printed. If pathnumber is followed by an m, then the pathnumber'th slowest path leading to a memory node is printed. If pathnumber is followed by a w then the pathnumber'th slowest path leading to a watched SunOS 5.6 Last change: 3 User Commands CRYSTAL(1) node is printed (see the watch command). Only the very slowest paths are recorded by Crystal, controlled by the paths, mempaths, and watchpaths options (see the options command below). Furthermore, Crystal does not record a path if its total delay is within .1% of another path already recorded on the list (this is to alleviate the problem of the lists getting flooded by essentially equivalent paths). If the file argument is given, then output goes to that file instead of stan- dard output. If the -g argument is given, a graphics command file is generated in graphicsfile. If the -s argument is given, a SPICE deck is created in spicefile describing the transistors and parasitics along the path (no model parameters or body bias voltages are output). delay node risetime falltime Propagate delay information through the circuit. Assume that the worst-case time for node to become 1 is risetime, and the worst-case time for it to become 0 is falltime. Propagate timing information through nodes that node can impact, until the the worst-case settling times for the entire network have been found. A -1 value for risetime or falltime means that there is no transition to that level. dump file This is a special wizards-only command for saving crit- ical path information in a way that Crystal can read it back later using the undump command, without having to reprocess the whole .sim file. Don't use this command unless you really know what you are doing. fillin time/edgeSpeed inFile outFile keyword path path ... This command is useful in order to interface Crystal to other programs that process Crystal's output. InFile is read by the command, and its contents are copied to outFile. Along the way, each occurrence of keyword is replaced by a number from one of the critical paths (each path is specified as for the critical command). If time is specified, then the time at the end of each stage along the critical path is used to replace occur- rences of keyword, with smaller times replacing earlier occurrences. If edgeSpeed is specified, then the edge speeds from the stages of the path are used to replace keywords. If more than one path is specified, the paths are processed in order of their occurrence on the command line. If there are more stages in the paths than occurrences of keyword, then the last stages are ignored. If there are more occurrences of keyword than stages, only the first few keywords will be replaced. If no path is specified, it defaults to ``1''. SunOS 5.6 Last change: 4 User Commands CRYSTAL(1) flow direction attribute attribute ... For each source/drain attribute given, mark the attribute so that information will only be permitted to flow in the given direction. Direction may be either in, out, off, ignore, or normal. In and out require information to flow only in the specified direction. Off does not permit any flow through the tagged tran- sistors. If ignore is specified then no restrictions are enforced whatsoever. Normal returns the flow to its normal operation. help Print a short listing of the valid commands. inputs node node ... Mark each of the nodes as an input. This has two effects. First, it indicates that the node can take on values of either 0 or 1 (otherwise, Crystal may con- clude that the node can't ever reach one or both val- ues). Second, if the node isn't also an output node, then Crystal assumes that the timing of the node is fixed by the outside world and is not affected by any- thing in the circuit: if no delay command is given for the node, Crystal assumes the value never changes. markdynamic node value node value ... This statement causes Crystal to examine all nodes and mark dynamic memory nodes. A node is considered to be a dynamic memory node if it is electrically isolated when each node takes its corresponding value. Normally the command is invoked with all of the clock phases turned off, e.g. ``markdynamic Phi1 0 Phi2 0 Phi3 0 Phi4 0''. model name Use name as the model for delay calculations. Cur- rently, two models, rc and slope, are available. The rc model approximates each transistor with a fixed resistance value. The slope model uses the gate rise and fall speeds to modify the effective resistance. options [name [value]] [name [value]] ... This command is used to see and set a variety of inter- nal options used by Crystal. Options with no arguments prints out the current setting of all options. Each option consists of an option name and perhaps a value for the option. Some options do not have values. See the section ``OPTIONS'' below for the available options. outputs node node ... Marks each of the given nodes as an output. Crystal assumes that information (0's and 1's) flows from SunOS 5.6 Last change: 5 User Commands CRYSTAL(1) sources (supply rails and inputs) to targets (gates and outputs). If a piece of circuit doesn't drive any gates, Crystal won't compute delays through it unless the result nodes are labelled as outputs. parameter [name] [value] This statement is used to see or change several overall model parameters. Name is the name of a parameter, and value is a new value for that parameter. If both name and value are specified, then the value of the parame- ter is changed. If only name is specified, then the current value is printed. If neither name or value is specified, then the values of all parameters are printed. The valid parameter names are listed in the section ``MODEL PARAMETERS'' below. prcapacitance [-g file] [-t threshold] node node ... Print out information for each of the indicated nodes whose total capacitance is at least threshold pf (the default is 0 if the argument isn't present). If no node names are given, then all nodes in the the circuit are checked. The -g argument can be used to generate a graphical command file. precharged node node ... Mark each of the given nodes as precharged. This means that only falling transitions are considered during timing analysis. Each of the nodes is also treated as a bus. predischarged node node ... Mark each of the given nodes as precharged to 0. This means that only rising transitions are considered dur- ing timing analysis. Each of the nodes is also treated as a bus. prfets node node ... For each node that is given, information is printed about all transistors whose gates attach to the node. If no node is specified, then information is printed about all transistors in the circuit. prresistance [-g file] [-t threshold] node node ... Print out information for each of the indicated nodes whose internal resistance exceeds threshold ohms. If no threshold is given, 0 is used by default. If no node names are given, then check all nodes in the cir- cuit. The -g argument is used to generate a graphics command file. quit Exit Crystal and return to the shell. End-of-file on the input stream will also cause Crystal to exit. SunOS 5.6 Last change: 6 User Commands CRYSTAL(1) ratio [limit value] [limit value] ... Examine the circuit for nMOS ratio violations. Normal circuits are expected to have pullup/pulldown ratios between 3.8 and 4.2. Pass transistor driven circuits must have ratios between 7.8 and 8.2. Ratios outside this range are printed out. If the same illegal pullup/pulldown ratio is duplicated more than 20 times, only the first 20 are printed. The limits of accept- ability may be changed by providing arguments to the ratio command. Limit must be one of normallow, nor- malhi, passlow, or passhi (unique abbreviations are acceptable). resistance ohms node node ... The internal node resistance associated with each node is set to ohms. This overrides the value computed from the mask layout. set value node node ... Force each node always to have the given value (0 or 1). Furthermore, do a static logic simulation to prop- agate this information as far as possible throughout the network. Thus, if the input to an inverter or NAND gate is forced to 0, the output is forced to 1, and so on. source file Read commands from file. On end-of-file, go back to reading commands from the previous source. Source files may be nested. statistics Prints a variety of statistics gathered internally by Crystal. Probably not useful except to a system main- tainer. transistor [name [field value] [field value] ...] The transistor command is used to define new transistor types, or see or modify existing types. Name is the name of a transistor type, field is the name of a field associated with the transistor, and value is a new value for that field. The valid field names are listed in the section ``TRANSISTOR FIELDS'' below. If name matches the name of an existing transistor type (see below for the predefined types), then the field and value arguments are used to change some of its fields. If name is not an existing transistor type, a new type is created. If there are no arguments to the transis- tor command, then all fields for all defined types are printed out. If name is supplied with no field values, then all the fields for that transistor are printed out. To use a user-defined type for a transistor, SunOS 5.6 Last change: 7 User Commands CRYSTAL(1) place an attribute on the gate of the transistor. The the attribute contains the name of the transistor type to use for it. undump file This is another wizards-only command. Don't use it unless you really know what you are doing. The undump command is provided to read back the output of the dump command, so that Crystal can get critical paths without having to re-extract them. watch node node ... Mark each of the given nodes so that delays to them will be recorded on the list of slowest watched nodes (these nodes will still be recorded on the lists of arbitrary and memory nodes too, if they are among the slowest in those categories). The watch flags are cleared by the clear command. OPTIONS The options defined below are used in various and sundry places inside Crystal to control calculations and printout. They can be changed with the options command. bus value Gives the amount of capacitance a node must have to automatically be considered a bus by Crystal (default is 2 pfs). graphics style Sets the style for graphical output. Currently, three styles are understood: caesar, magic, and squid (default is caesar). limit value Gives the maximum of stage delays Crystal will calcu- late before giving up in despair (default is 200000). mempaths value Gives the number of worst-case paths Crystal will record for delays to memory nodes (default is 5, maxi- mum is 100). noprintedgespeeds When printing critical paths, print only the delay to each node, without the edge rise or fall speeds (default). noseedelays Tells Crystal not to print out information about delays as they are calculated in delay commands (default). SunOS 5.6 Last change: 8 User Commands CRYSTAL(1) noseedynamic Tells Crystal not to print out the dynamic memory nodes as they are found in the markdynamic command (default). noseesettings Tells Crystal not to print out nodes when they are set to values during the set command (default). paths value Gives the number of worst-case paths Crystal will record on the list of slowest nodes overall (memory nodes and watched nodes will also be recorded on lists for each of those categories; mempaths and watchpaths options are used to control the lengths of those lists). The default is 5 and the maximum is 100. printedgespeeds When printing critical paths, in addition to printing the delay to each node, also print the speed at which the edge rises or falls at that node. This only makes sense when using the slope model. ratiodups value When printing out ratio errors in the ratio command, if a number of errors occur with exactly the same erro- neous ratio, only the first ratiodups of these dupli- cate errors will be printed. The default is 20. ratiolimit value Controls the maximum number of ratio errors that will be printed in any one ratio command. The default is 1000. seealldelays Causes Crystal to print out each new delay as it is calculated during the delay command. seeallsettings Causes Crystal to print out each node setting as it is found during the set command. seedelays Causes Crystal to print out new delays as they are found during the the delay command, but only for nodes whose names have alphabetic first characters. seedynamic Causes Crystal to print out the name of every dynamic node as it is found in markdynamic. seesettings Causes Crystal to print out new node settings during SunOS 5.6 Last change: 9 User Commands CRYSTAL(1) the set command, but only for nodes whose names have alphabetic first characters. units value Tells Crystal what units to use when printing out information. If units is 2.0 (default) then a printed value of 1 corresponds to 2 microns. watchpaths value Gives the number of paths to record on the list of slowest watched nodes (default is 5, maximum is 100). TRANSISTOR FIELDS Each transistor type is parameterized by the following fields. They can be changed using the transistor command. cperarea Gate-channel capacitance of the transistor, in pfs per square micron. cperwidth Gate-source and gate-drain overlap capacitance, in pfs per micron of transistor width. histrength An integer value giving the logical strength of the transistor when it is pulling to Vdd. This is used in simulation to determine which transistor wins when dif- ferent transistors drive a node in different directions (e.g. histrength for pullup loads is less than lostrength for enhancement pulldowns). lostrength An integer value giving the logical strength of the transistor when it is pulling to ground. on This field has one of three values: gate0, gate1, or always. Gate0 means that the transistor is turned on only when the gate is zero (in other words, it is a p- channel enhancement device). Gate1 means that the transistor is turned on only when the gate is one (it is an n-channel enhancement device). Always means the device is always turned on (it is a depletion device). rdown The resistance per square of the transistor when it is pulling down. Used to calculate delays in the rc model. rup The resistance per square of the transistor when it is pulling up. Used to calculate delays in the rc model. SunOS 5.6 Last change: 10 User Commands CRYSTAL(1) slopeparmsdown Gives table values used for interpolation in the slope delay model. The value consists of any number of triplets. Each triplet contains an edge speed ratio, an effective resistance, and an output edge speed. The table is used when the transistor is driving to ground. The mkcp program is useful for generating these parame- ters from SPICE model parameters. slopeparmsup Gives table values used for interpolation in the slope delay model. The value consists of any number of triplets. Each triplet contains an edge speed ratio, an effective resistance, and an output edge speed. The table is used when the transistor is driving to Vdd. The mkcp program is useful for generating these parame- ters from SPICE model parameters. spicebody Spicebody is the node number to use for the body when outputting this type of transistor in SPICE decks. The body node number must be 0-3. 0 is GND, 1 is Vdd, and 2 and 3 are user-controlled body bias voltages. spicetype A single letter identifier used as the type of this transistor in SPICE decks. PREDEFINED TRANSISTOR TYPES The following types of transistors are predefined by Crys- tal. When Crystal reads in files, it selects one of the following transistor types for each transistor, unless over- riden by an attribute giving a type not listed below. Their fields can be changed using the transistor command. nenh Enhancement transistors in nMOS. nenhp Enhancement transistors in nMOS whose gates are driven by pass transistors (i.e. any transistor whose gate is not a circuit input and does not attach to an nload or nsuper transistor). Transistor types are switched between nenh and nenhp during flow marking. ndep Depletion devices in nMOS (most depletion devices are turned into either type nload or nsuper by Crystal). nload nMOS depletion devices where the gate connects to either source or drain and the other terminal connects to Vdd. SunOS 5.6 Last change: 11 User Commands CRYSTAL(1) nsuper nMOS depletion devices where either the source or drain connects to Vdd but the other terminal doesn't connect to the gate. nchan N-channel enhancement devices in CMOS. This is pro- vided separately from type nenh as a convenience to accomodate different delay characteristics in nMOS and CMOS. pchan P-channel enhancement devices in CMOS. MODEL PARAMETERS The following are the model parameters that aren't associ- ated with particular transistor types. They are used in the parameter command. diffcperarea Capacitance between diffusion and substrate, in pfs per square micron. diffcperperim Sidewall capacitance of diffusion, in pfs per micron of perimeter. diffresistance Resistance of diffusion, in ohms per square. metalcperarea Capacitance between metal and substrate, in pfs per square micron. metalresistance Resistance of metal, in ohms per square. polycperarea Capacitance between polysilicon and substrate, in pfs per square micron. polyresistance Resistance of polysilicon, in ohms per square. vdd The supply (logic 1) voltage. Used in the slope model, and also in outputting SPICE decks. vinv The logic threshold voltage (usually Vdd/2). Used in the slope model to compute edge speeds for resistors. SunOS 5.6 Last change: 12 User Commands CRYSTAL(1) SEE ALSO mkcp(1) AUTHOR John Ousterhout SunOS 5.6 Last change: 13