User Commands ESIM(1) NAME esim - event driven switch level simulator SYNOPSIS esim [file1 [file2 ...]] DESCRIPTION Esim is an event-driven switch level simulator for nMOS or CMOS transistor circuits. Esim accepts commands from the user, executing each command before reading the next. Com- mands come in two flavors: those which manipulate the elec- trical network, and those to direct the simulation. Com- mands have the following simple syntax: c arg1 arg2 ... argn where c is a single letter specifying the command to be per- formed and arg1 through argn are arguments to that command. The arguments are separated by spaces or tabs, and the com- mand is terminated by a newline. To run esim type esim file1 file2 ... Esim will read and execute commands, first from file1, then file2, etc. If one of the file names is preceded by a '-', then that file becomes the new output file (the default out- put is stdout). For example, esim f.sim -f.out g.sim This would cause esim to read commands from f.sim, sending output to the default output. When f.sim was exhausted, f.out would become the new output file, and the commands in g.sim executed. After all the files have been processed, and if the q com- mand has not terminated the simulation run, esim will accept further commands from the user, prompting for each one like so: sim> The user can type individual commands or direct esim to another file using the @ command: sim> @ patchfile.sim This command would cause esim to read commands from patch- file.sim, returning to interactive input when the file was exhausted. It is common to have an initial network file prepared by a node extractor with perhaps a patch file or two prepared by hand. After reading these files into the simulator, the user would then interactively direct esim. This could be accomplished as follows: esim file.sim patch.1 patch.2 After reading the files, esim would prompt for the first command. Or we could have typed: % esim file.sim SunOS 5.6 Last change: 4/18/82 1 User Commands ESIM(1) sim> @ patch.1 sim> @ patch.2 Network Manipulation Commands The electrical network to be simulated is made up of enhancement and depletion mode transistors interconnected by nodes. Components can be added to the network with the fol- lowing commands: e gate source drain e gate source drain length width key xpos ypos area Adds enhancement mode transistor to network with the specified gate, source, and drain nodes. The longer form includes size and location information as provided by the node extractor -- when making patches the short form is usually used. d gate source drain d gate source drain length width key xpos ypos area Like e except for depletion mode devices. p gate source drain p gate source drain length width key xpos ypos area Like e except for pMOS devices in CMOS. n gate source drain n gate source drain length width key xpos ypos area Like e except for nMOS devices in CMOS. C node1 node2 cap Increase the capictance between node1 and node2 by cap. Esim ignores this unless either node1 or node2 is GND. = node name1 name2 name3 Allows the user to specify synonyms for a given node. Used by the node extractor to relate user- provided node names to the node's internal name (usually just a number). | comment... Lines beginning with vertical bar are treated as comments and ignored -- useful for deleting pieces of network in node extractor output files. i node Input record -- output by node extractor and not used by esim. Currently, there is no way to remove components from the network once they have been added. You must go back the input files and modify them (using the comment character) to exclude those components you wished removed. N records need not be included for new nodes the user wishes to patch into the network. Simulator Commands The user can specify which nodes are to have there values displayed after each simulation step: SunOS 5.6 Last change: 4/18/82 2 User Commands ESIM(1) w node1 -node2 node3 ... Watch node1 and node3, stop watching node2. At the end of a simulation step, each watched node will displayed like so: node1=0 node3=X ... To remove a node from the watched list, preface its name with a '-' in a w command. W label node1 node2 ... noden Watch bit vector. The values of nodes node1, ..., noden will displayed as a bit vector: label=010100 20 where the first 0 is the value of node1, the first 1 the value of node2, etc. The number displayed to right is the value of the bit vector inter- preted as a binary number; this is omitted if the vector contains an X value. There is no way to unwatch a bit vector. Before each simulation step the user can force nodes to be either high (1) or low (0) inputs (an input's value cannot be changed by the simulator!): h node1 node2 .. Force each node on the argument list to be a high input. overrides previous input commands if nec- essary. l node1 node2 ... Like h except forces nodes to be a low input. x node1 node2 ... Removes nodes from whatever input list they happen to be on. The next simulation step will determine their correct value in the circuit. This is the default state of most nodes. Note that this does not force nodes to have an X value -- it simply removes them from the input lists. The current value of a node can be determined in several ways: v View. prints the values of all watched nodes and nodes on the high and low input lists. ? node1 node2 ... Prints a synopsis of the named nodes including their current values and the state of all transis- tors that affect the value of these nodes. This is the most common way of wondering through the network in search of what went wrong... ! node1 node2 ... For each node in the argument list, prints a list of transistors controlled by that node. ? and ! allow the user to go both backwards and forwards through the network in search of that piece causing all the problems. SunOS 5.6 Last change: 4/18/82 3 User Commands ESIM(1) The simulator is invoked with the following commands: s Simulation step. Propogates new values for the inputs through the network, returns when the net- work has settled. If things don't settle, command will never terminate -- try the w and D commands to narrow down the problem. c Cycle once through the clock, as define by the K command. I Initialize. Circuits with state are often hard to initialize because the initial value of each node is X. To cure this problem, the I command finds each node whose value is charged-X and changes it to charged-0, then runs a simulation step. If one iterates the I command a couple times, this often leads to a stable initialized condition (indicated when an I command takes 0 events, i.e., the cir- cuit is stable). Try it -- if circuit does not become stable in 3 or 4 tries, this command is probably of no use. Miscellaneous Commands D toggle debug switch. useful for debugging simula- tor and/or circuit. If debug switch is on, then during simulation step each time a watched node is encounted in some event, that fact is indicated to the user along with some event info. If a node keeps appearing in this prinout, chances are that its value is oscillating. Vice versa, if your circuit never settles (ie., it oscillates) , you can use the D and w commands to find the node(s) that are causing the problem. > filename write current state of each node into specified file. useful for make a break point in your simu- lation run. Only stores values so isn't really useful to dump a run for later use -- see < com- mand. < filename read from specified file, reinitializing the value of each node as directed. Note that network must already exist and be identical to the network used to create the dump file with the > command. These state saving commands are really provided so that complicated initializing sequences need only be simulated once. L SunOS 5.6 Last change: 4/18/82 4 User Commands ESIM(1) invokes network processor that finds all subnets corresponding to simple logic gates and converts them into form that allows faster simulation. Often it does the right thing, leading to a 25% to 50% reduction in the time for a single step. [We know of one case where the transformation was not transparent, so caveat simulee...] X ... call extension command -- provides for user exten- sions to simulator. q exit to system. Local Extensions V node vector Define a vector of inputs for the node. The first element is initially set as the input for node. Set the next element of the vector as the input after a cycle. G n Run the simulator through n cycles (a group). If n is not present make the run as long as the longest vector. All watch nodes are reported back as vectors. N Clear all previously defined input vectors. K node1 vector1 node2 vector2 ... nodeN vectorN Define the clock. Each cycle, nodes 1 through N must run through their respective vectors. SEE ALSO ext2sim(1), sim(5) AUTHOR Chris Terman CMOS enhancements by Mike Klein and Joan Pendelton Changed the old "R" (run) command name to "G" (group) to avoid nam- ing conflict with Resistor declations from the extracted files (by Fred W. Obermeier). SunOS 5.6 Last change: 4/18/82 5