Inter-Office Memorandum To Thyme Interest Date July 11, 1983 From Rick Barth Location Palo Alto Subject Thyme Manual Organization PARC/IDL XEROX Filed on: [Cherry]Top>ThymeManual.tioga, .press Thyme Manual Introduction This is the manual for Thyme as available for Alto/Mesa 6.1 during July, 1983. Thyme is a circuit simulation system to help you predict the time domain response of an MOS integrated circuit. There are a number of tools that assist you in preparing Thyme input and analyzing Thyme output. The circuit extractor, which is a component of Chipmonk, lets you create Thyme input files from existing layout. PlotScreen allows Thyme output to be displayed on a color display. PlotPress converts Thyme output into press files suitable for printing on Lilac. Thyme is already capable of handling simulations with hundreds of nodes and components. In future versions, it will be converted to run in the Cedar programming environment, where it will provide much better output analysis capabilities. Thyme and initial drafts of portions of this document were written by Neil Wilhelm. Further maintenance and enhancement has been done by Rick Barth and Sweetsun Chen. Thyme is solely a time domain circuit simulator. It has far fewer capabilites than other circuit simulators, most notably Spice, but it is much easier to use for the particular task for which it was designed. In particular Thyme will handle larger circuits, has a more powerful circuit specification language, and produces output which is easier to analyze. Thyme is quite easy to maintain compared to Spice. Last but not least it runs on machines that are widely available within our design environment, namely D machines. How To Get Started Installation The following installation procedure assumes that you have a vanilla Mesa 6 Alto partition with a reasonable amount of disk space available. The additional files beyond those which are left on a newly erased disk which you must have include RunMesa.run and Mesa.image. It is also a good idea to have XDebug.image on your disk and have the debugger installed so that if you run into problems the Thyme maintenance people have some hope of helping you. In Palo Alto the local directory which contains these files is [Ivy]. To install Thyme on your machine retrieve [Cherry]Top>ThymeGet.cm and invoke it as a command file by typing @ThymeGet to the Alto Executive. This will retrieve the following files: ThymeForm.thy A working input file to start editing with. Extract.chipbcd A version of the extractor that is compatible with the current Thyme. Thyme.bcd The simulator itself. Thyme.errors Contains the text of the error messages Thyme generates . ThymeBasics.thy Links the simulator to the model and function definitions. MosModels.thybcd Contains the transistor model code. StdFunctions.thybcd Contains the waveform generation code. PlotPress.bcd Converts the .plot files generated by Thyme into .press files suitable for tranmission to Lilac. PlotScreen.bcd Replots the first page of a .plot file on the screen. Helvetica8.ks Font used to print characters on the plot. If you start up Thyme and it simply hangs there with a cursor that is a circle with an arrow in it then you are probably missing the font file. The plotting software is starting at Helvetica8.ks, looking it up in the file directory, discovering it is not there, changing the font filename to Helvetica9.ks, looking for it, not finding it, etc. etc. until the string overflows or your patience runs out, whichever occurs first. You must also retrieve the correct process definition file for the type of simulation you intend to do. These files are stored in the subdirectory [Cherry]ProcessDefs>. The filename depends on the type of process you are using, the minimum feature size in microns, and the temperature at which you intend to do your simulation. See the section about circuit design pragmatics later in this document for a detailed discussion of how to choose the correct temperature. If you are learning how to do circuit simulation and know the process type and minimum feature size just use the highest temperature data available for your simulations rather than plunging off into a morass of detail that need not concern you right now. For example if you are using an NMOS process with a 4m feature size then you should retrieve the file [Cherry]ProcessDefs>NMos4.0u75.thy. Note that the character in the filename is a "u" not a "m". Process definition filenames have the form ||.thy. Preparing Input Thyme input may be generated in two ways. One is to sit down with your favorite text editor and type it in. The other is to lay out your circuit using Chipmonk and then apply the circuit extractor to your layout. In this section we will assume that you are doing the former, how to make Thyme work in the latter case we will handle subsequently. This section is an overview. As such much of the detail has been suppressed. Don't treat it as the gospel truth. That's saved for later. The basic format of a Thyme file is: library statements circuit definition output control run control and here is an example of one: 1 library[MosModels]; 2 library[StdFunctions]; 3 circuit={ 4 !ThymeBasics.thy 5 !Nmos4.0u75.thy 6 in:node; out:node; Vdd:node; 7 powerSupply: voltage[Vdd, Gnd]= 5.0; 8 ?:capacitor[out,Gnd] = 0.01pF; 9 ?:Dep[out,out,Vdd | L _ 4, W _ 2]; 10 ?:Enh[in,Gnd,out]; 11 ?:RectWave[in|period_ 4us, width _ 2us, tRise _ 0.1us, tFall _ 0.1us, tDelay _ 2us]; 12 }; 13 plot["Nmos Inverter (4 micron, 75 C)", :0.1us, -1, 6, in, out]; 14 run[TMAX _ 10us]; Note that the line numbers appear here purely for expository purposes and are referred to below in parantheses. The library statements (1-2) cause Thyme to load the model and function code. These statements must always appear and it is unlikely you will ever want to change them. If you think you do details are available further on in this document. The circuit definition part (3-12) contains two references to other files which are to be included as if their contents were present in this file. The first one (4) defines the interface for the model code which was loaded in the library statements and the second one (5) tells the model code which particular process you are using. Again these statements always appear and it is unlikely you will change them except for the choice of the second filename. The rest of the circuit definition part (6-12) defines a simple inverter circuit that has a rectangular wave as input and a single capacitor as the output load. All the statements defining the circuit have the form name:type;, where a name is an alpha followed by a sequence of alphnumerics and type is a name previously defined or a built in type. If you don't care to give a name to a particular instance then you may put a "?" in place of the name, Thyme will generate a name for you. If you want to use funny kinds of names that include characters such as ";" then you must surround the name with "$". A type must be defined before it is used; otherwise order does not matter. A circuit is a collection of nodes, branches, and subcircuit instantiations. First the nodes are defined (6) and then the branches (7-8) and subcircuits (9-11) are instantiated using the nodes previously defined. Node definitions have the form: : node There is one predefined node, Gnd, the ground node. All voltages are referenced to it. Branch instantiations have the form: : [, ] = Branches may be one of the following built in types: RESISTOR, CAPACITOR, INDUCTOR, VOLTAGE, and CURRENT. Each of these expects a numeric value to be following the "=" in units of volts, amps, ohms, farads, or henries. The left node name of a branch is considered to be the positive terminal of the branch. All numbers read by Thyme are real although fixed point representations will be accepted and converted. Thyme has a primitive understanding of units of measurement. A unit may be specified with any number; it must immediately follow the number with no intervening spaces. Acceptable units are "A," "F," "H," "s," and "V," for amperes, farads, henries, seconds, and volts. Scaling factors may be prefixed onto a unit; the available ones are "M," "K" or "k," "m," "u," "n," and "p," which stand for mega-, kilo-, milli-, micro-, nano-, and pico- respectively, e.g. pF (8) stands for picofarads. A subcircuit is another collection of nodes, branches and subcircuit instantiations. For the simple circuit we are dealing with here we do not need to know how to define our own subcircuits but we do need to know how to instantiate subcircuits since that is how transistors are implemented. Subcircuit instantiations have the form: : [|] The circuits being instantiated here are a depletion transistor (9), an enhancement transistor (10), and a rectangular waveform generator (11). Transistors have their nodes in the order gate, source, drain. The actual parameters for a transistor are "L" and "W" which define the channel length and width respectively. The plot statment (13) is the output control part of the input file. It tells Thyme to label a plot with "Nmos Inverter (4 micron, 75 C)", scale the x axis so that a one on the axis is equal to 0.1 microsecond, set the y axis min to -1 volt and max to 6 volts, and finally to plot the voltage on nodes "in" and "out". The run statement (14) is the run control part of the input file. It causes Thyme to actually begin simulation, starting at time=0 and continuing until time is greater than or equal to TMAX, here ten microseconds. Running It Assume that you have prepared your input file as described in the previous section and that you have called it "Foo.thy". This section describes how to run Thyme, control it during execution and print your results. The format of the command line to start Thyme looks like: Thyme . Currently the field, which is optional, may only be /c, which is the default and causes the color display to be used, or /-c to indicate that no color display is available. If you wish Thyme to read its input from "Foo.thy" then "Foo" for . is sufficient. If you have a file named "Foo.baz" where "baz" is not "thy" then the must be explicitly stated. If you do not specify a file name on the command line or if Thyme cannot find the file it will prompt you for a file name. After Thyme has successfully opened the input file it will echo the input to the display as it is read while displaying the word "Thyme" in the cursor. If no error is detected during input then Thyme sets the cursor to a bomb and flattens the circuit so that each component is instantiated. Then the cursor changes to an exploded bomb and a few legality checks are performed on the exploded circuit. Finally the cursor will be set to a clock with one hand and the simulation will begin. Each time the solution of the circuit is advanced by one time step the hand on the clock will spin 90 degrees. While the clock hand is spinning the keyboard is also being sampled at a low frequency. So, if you hold down Control, Left Shift, and some other key, Thyme will take the actions listed in the table below: Key Action Q Terminates the simulation and forces a dump file to be made. T Terminates the simulation. H Toggles the "hold" bit: if the "hold" bit is set, Thyme pauses when the simulation is over. The state of the hold bit is displayed by video reversing the cursor. D Toggles the color display on and off. Because the keyboard is being examined about once each second, you will have to hold the key down at least that long. The listing of your input file is placed in mesa.typescript. Another file, .log, is produced. This file contains any syntax or semantic errors that Thyme may have detected, as well as miscellaneous run-time information. The plot output will be placed in .plot and any print output you may have requested will be placed in .out, where is the number of the print statement. Making Pictures To convert your Foo.plot file into Foo.press type PlotPress Foo to the exec. Naturally Foo.press may be sent to your favorite printer using Empress. If you generated a color display while the simulation was running then you must send the .press file to a color printer such as Lilac, and if you generated a black and white display you should send the resultant press file to a black and white printer. You can also put the first plot in a .plot file back up on the screen by typing PlotScreen Foo to the exec. Unfortunately there is no way to display more than the first plot. If you are using Lilac as your printer then you should beware that it will not print more than 4 pages reliably and the first page invariably has registration problems. Plan accordingly. If you are reading this document for the first time and have not yet run Thyme you should do so now before you read the rest of this. Thyme and the Circuit Extractor Suppose that you have laid out a circuit and would like to simulate it using Thyme. The first thing you do is run the circuit extractor which will produce a file say Foo.thy. This section explains what you need to do to provide the additional input Thyme requires to do a simulation. The circuit extractor produces a file which describes the circuit in terms of the amount of area and periphery each of the interconnect layers contributes to each electrical node and the size and connection of each of the transistors. The interconnect size must be transformed into resistive-capactive networks which approximate the DC and AC loading the interconnect places on the circuit. The transistor sizes must be transformed into the parameters required by the transistor model code. This is done by a collection of circuits found in each of the process definition files. If you were to lay out the inverter circuit used in the first example and extract it, the resulting file would look something like the following: 1 -- N o d e s 2 3 INPUT:node; ?:Stray[INPUT|aP_36]; 4 -- Vdd:node; ?:Stray[Vdd|aD_26,pD_30]; 5 -- Gnd:node; ?:Stray[Gnd|aD_30,pD_30] 6 OUTPUT:node; ?:Stray[OUTPUT|aM_24,aP_44,aD_20,pD_18]; 7 8 -- T r a n s i s t o r s 9 10 Q1:DTran[OUTPUT,OUTPUT,Vdd]; 11 Q2:ETran[INPUT,Gnd,OUTPUT]; The file which you must edit to run the circuit simulation using the extracted circuit should look like the following: 1 library[MosModels]; 2 library[StdFunctions]; 3 circuit={ 4 Vdd:node; 5 powerSupply: voltage[Vdd, Gnd]= 5.0; 6 !ThymeBasics.thy 7 !Nmos4.0u75.thy 8 !Foo.thy 9 ?:capacitor[OUTPUT,Gnd] = 0.01pF; 10 ?:RectWave[in|period_ 4us, width _ 2us, tRise _ 0.1us, tFall _ 0.1us, tDelay _ 2us]; 11 }; 12 plot["Nmos Inverter (4 micron, 75 C)", :0.1us, -1, 6, in, out]; 13 run[tMax _ 10us]; The output capacitor still appears to model portions of the circuit which do not appear in the extracted description. The only real difference here is that the nodes and transistors of the circuit are no longer typed in but are included by line (8). Circuit Specification Suppose that you have a collection of circuits that you need to put into your simulation that are all essentially the same except for component values. An easy way to accomplish that task is to define your own circuit. The following skeleton shows how such circuits may be defined and then used. 1 circuit[] = { 2 : node; 3 : circuit[|] = { 4 : node; 5 : resistor[, ] = ; 6 }; 7 : resistor[, ] = ; 8 : [|] 9 } A subcircuit is defined in statements (3-6). The node names used in the definition of the resistor (5) may be from the node statment within the subcircuit (4) or from the connection name list that appears in the subcircuit definition statment (3). Variables used in the expression which computes the value of the resistor (5) may come from any of the parameter definition lists (1) or (3). The node names which appear in the first node statement (2) may be used in the instantiation of the subcircuit in statement (8). Elements of lists are separated by commas. A parameter definition is either or _ , which gives the parameter a default value. An actual parameter has the form _ ; the order of appearance of the actual parameters does not matter. The usual rules and operators apply to . The example below defines a circuit which one can use to test the response of a two stage RC model of a diffusion line to a step input. circuit[width _ 2, len _ 100, lambda _ 2.5] = { diffusion: circuit[in, out|w, l, rho _ 35, cap _ 20e-5pF] = { r: resistor[in, out] = rho*l/w; c: capacitor[out, Gnd] = cap*l*w*lambda^2}; input, middle, output: node; step: voltage[input, Gnd] = 5; section1: diffusion[input, middle|l _ len/2, w _ width]; section2: diffusion[middle, output|l _ len/2, w _ width]} Two of the parameters of the circuit diffusion have default values, the sheet resistivity, rho, and the area capacitance, cap. More About Output Control Output control is made up of and which tell Thyme what sort of output to produce. The maximum number of 's or 's is ten and they may be freely mingled. The file names of the output files specified by the 's are generated by .out with the first one in sequence being numbered zero. The first determines what will appear on your computer's display; all the plots will have the same aspect ratio and format. The formats for the and are: print[