A Circuit Design consists of a collection of Subcircuit Designs. A Circuit Design is a hierarchical decomposition, and Subcircuit Designs are the nodes in the hierarchy.

A Subcircuit Design has an Interface, through which it communicates with the rest of the design. A Subcircuit Design's Interface is a set of Items, each of which has a name (text string), an Abstract Type (described later), and a Direction (one of In, Out, or Both).

Given that we have restricted ourselves to describing systems to be built in silicon, we might insist that all Interface Items have the same Abstract Type: that Type would be the only one, the one corresponding to a single electrical node. Or we might distinguish more finely, and make three, one for each of the three primary layers of interconnect (poly, metal, and diffusion). Aside from that issue, we could think of Interfaces as trafficing in Boolean values, or voltages, or any one of a number of other things. Still further, we could imagine treating a collection of wires as a single unit (i.e., a single Interface Item), rather than many individuals. Abstract Types do not make any of those decisions. As far as we are concerned here, Abstract Types have nothing but an identity. They are used only in the following way: when two things are connected, we insist that they have the same Abstract Type.

A Subcircuit Design might, but does not need to, include a description of how it is composed of other Subcircuits (its Structural Description). Such a description is in terms of Instances of other Subcircuit Designs, and Abstract Networks connecting them. An Instance of a Subcircuit Design includes an association between each of the Items of the Interface of that Subcircuit Design and an Abstract Network. Furthermore, each of the Interface Items of the Subcircuit Design we are elaborating must also be associated with an Abstract Network. Thus, these associations describe how things are connected: all of the Interface Items associated with a particular Abstract Network are considered connected together. We insist that they all be of the same Abstract Type.

A Subcircuit Design might also, but also does not need to, include a description of what the outputs of an Instance of that Subcircuit would be, given the inputs (its Behavioral Description). This description might be a procedure, which is allowed to keep a state record, in some programming language.

A Subcircuit Design might also, but also does not need to, include a non-constructive Behavioral Description; one that can provide stimuli, observe the results, and approve or dissapprove. This description is called the Subcircuit Design's Test. It may also be a procedure in some programming language.

Forget the preceeding discussion. We will now discuss how a fairly general simulator might be built. Call it the Structural Simulator.

This simulator will not deal with hierarchy. It will have a single, flat, Structure. Furthermore, it will deal only with unidirectional devices. The Modules in such a structure will have outputs which are computable functions of the histories on their inputs.

A Simulation Structure will consist of Modules, connected up. The methodology for connecting is like that presented in section 1.1, but you've forgotten that, haven't you? Just to keep things clear, we will use different words.

Each Module will communicate via a Cedar RECORD. Each field will be either an input, an output, or both. Each Module will have an Evaluation PROCEDURE, which examines the input fields, does some computation, and assigns into some output fields. Each Module will have a REF ANY slot in which to store arbitrary state information from one invocation to the next. Each of the output fields has associated with it a Distribution List of input fields of other Modules. After a Module's Evaluation PROCEDURE has been run, for each output field that has changed, the bits in that field are copied into all of the fields on its Distribution List.

A Simulation Structure will also have a FIFO, called its Schedule. The Schedule contains Modules whose inputs have changed since their Evaluation PROCEDUREs were last run. Modules are added to the Schedule at the time their inputs change. The main loop of the simulator is to take the first Module out of the Schedule, run its Evaluation PROCEDURE, and take care of all the grubby little details, terminating when (and if!) the Schedule empties. If you start with a quiescent Structure, and make a small change, this makes for a breadth first exploration of the consequences of that change.

OK, now you can stop forgetting section 1.1. Rosemary has a Cedar data structure that represents concepts from both Circuit Designs and Simulation Structures. Rosemary simulates, by virtue of the efforts of possibly more than one Simulation Structure, and even other simulators, the operation of an Instance of a Circuit Design (that is, an Instance of a certain distinguished Subcircuit: its Root).

In Rosemary, Cells are used to represent Instances of Subcircuit Designs. For every Instance there is exactly one Cell. Furthermore, there are no Cells that do not represent Instances.

Rosemary includes an implementation of the simulator discussed in section 1.2. Its Modules are also represented by Cells, although it is not the case that all Cells must represent Modules.

Rosemary has another TYPE of object, Node, that is used to represent both the Abstract Networks of Subcircuit Designs, and the Distribution Lists of Simulation Structures.

When Instantiating a Subcircuit Design for simulation, either its Structural Description or its Behavioral Description could be used (assuming, of course, they are both present). When creating the data structure for a Rosemary simulation, a Subcircuit Design is always Instantiated in the context of some Simulation Structure. If the Subcircuit's Behavioral Description is to be used, a Module is introduced into that Simulation Structure. The Evaluation PROCEDURE of that Module is the Subcircuit's Behavioral Description.

If, on the other hand, the Subcircuit Design's Structural Description is to be used, there is a choice of how to use it. One alternative, Nested, also introduces a new Module into the Simulation Structure. It then introduces a new Simulation Structure, "inside" the Module, to implement that Subcircuit in terms of its components. The Evaluation PROCEDURE of the Module is another instance of the main loop of the Structural Simulator, directed at the inner Simulation Structure.

When the Nested alternative is used, new Nodes are created, in the inner Simulation Structure, corresponding to the Nodes in the outer Simulation Structure that are on the Interface of the Cell. That is, there are two sets of interface Nodes for such a Cell: one seen from the outside, and one seen from the inside. The ones seen from the outside are the ones entered in the interfaceNodes field in the Cell. The ones seen from the inside are put in the internalNodes SymbolTable.

The other alternative, Inline, does not introduce a new Module, nor a new Simulation Structure. It causes the components to be Instantiated in the same Simulation Structure.

The practical import of choosing one or the other is in the ordering of evaluations. In the Nested choice, when the nested Module is evaluated, it is run to completion before anything on the outside world may continue. In the Inline choice, there is no distinction between inside and outside; they mix freely. Inline is probably the one you want. The real reason for having Nested around it to start to debug ideas about plugging different simulators together.

Here are some highlights from Rosemary.Mesa, a DEFINITIONS file that has most of the relevant definitions in it:

The type of a Cell distinguishes those that represent Modules from those that do not; Real Cells represent Modules, and Shadow Cells represent Instances of Subcircuit Designs that have no Module (i.e., are Inlines). A CellClass represents a Subcircuit Design. The internalNodes SymbolTable of a Cell holds the Nodes that are used in connecting up the components of the Cell. The components SymbolTable holds the Subcircuit Design Instances from which that Cell is composed.

The interfaceNodes field holds the association between Interface Items of the Subcircuit Design and the Abstract Networks they are associated with. For I in [0 .. class.ports.length), interfaceNodes[I] represents the Abstract Network associated with the Interface Item represented by class.ports[I].

For Real Cells (that is, ones that also represent Modules in a Simulation Structure) there is an additional record that holds additional information: the realCellStuff. The Schedule of the Simulation Structure is a linked list, and the links are the schedNext fields. The newIO field holds a REF to the RECORD used by the Evaluation PROCEDURE. For the benefit of the simulator, it is duplicated as a LONG POINTER TO CARDINAL in newIOAsWP. The oldIO is used for detecting changes in newIO. The eval field holds the Module's Evaluation PROCEDURE, and the state field is for whatever use the Evaluation PROCEDURE wants to put it to.

Nodes hold the Distribution Lists of the Structural Simulator. A Distribution List is represented by a SocketList. The index in a Socket is into a table stored with the Class of the Cell referred to, which tells the simulator where to stuff the bits.

As was mentioned earlier, all of the Interface Items associated with a given Abstract Network must be of the same Abstract Type. That Type is stored in the Node. SignalTypes are used to represent Abstract Types.

Although Abstract Types have nothing but an identity, SignalTypes have more. But what they have is (mostly) just for constructing user interface; as far as most of Rosemary is concerned, only their identity is important. The ToRopeProc, FromRopeProc, MaxWidthProc, TestParseProc, and TestUnParseProc are for formatting and parsing Tests and Values (see discussion of mode in section 3.3). The TypeInitProc is used to provide a default initial value for fields in newIO.

SignalTypes are usually gotten by calling some peripheral procedure that creates them. "IntTypes.Mesa" is a file containing an interface that provides such a procedure; it can be found in the example. "Mnemonics.Mesa" is another.

A CellClass represents a Subcircuit Design. The ExpandProc holds its Structural Description. It is a procedure, which, when executed, calls certain other procedures (CreateNode and CreateCell); these calls describe to Rosemary how an Instance of this Subcircuit Design is constructed out of Instances of others.

In CreateNode and CreateCell, the within parameter identifies the Instance being elaborated.

When calling CreateCell, the association between the Interface Items of the Instance being created and Abstract Networks is specified in the interfaceNodes parameter. It is of the format <id> ":" <id> ( "," <id> ":" <id> ) * . In each pair, the first <id> identifies the Interface Item (by the name of a Port), and the second identifies the Abstract Network (by the name of a Node). An alternative format elides the first <id> and colon of all the pairs; the association is then positional.

The IOCreator is called when the Class is Instantiated using its Behavioral Description, or using its Structural Description in the Nested fashion. The sole purpose of the IOCreator is to allocate RECORDS of the appropriate TYPE and put REFS to them in newIO and oldIO.

The Initializer is called under the same circumstances as the IOCreator. The reason for splitting them is to allow the fields of the IO RECORDS to be initialized according to the whims of their SignalTypes. The Initializer can then override those initializations, if it is so desired. The Initializer is passed a further flag, leafily, which distinguishes the two cases in which it might be called. It is TRUE when the Behavioral Description is being used. In this case, the Initialzer is also responsible for allocating the state RECORD that the Behavioral Description will use, and putting a REF to it in the state field of the Cell.

The ExpandProc, the IOCreator, and the Initializer all take a parameter, initData, which is for whatever use they choose to put it to. The initData handed to CreateCell is what will be given to the ExpandProc, IOCreator, and Initializer of the Class of Cell being created.

The eval EvalProc holds the Behavioral Description of the Subcircuit Design. It is a procedure which computes from the input fields of newIO the new values for the output fields of newIO. The way changes in the output fields are detected is as follows. Before doing anything else, the EvalProc must copy all the ouptut fields of newIO into the output fields of oldIO. Then it computes, and updates the output fields of newIO. The simulator then compares the bits in the output fields of newIO with those of oldIO. Note that the simulator treats these simply as a collection of bits. Thus, putting pointers there probably won't work "right" (and putting REFs there is almost certain to confuse the garbage collector). The Structural Simulator uses the information in the ports sequence of the Class of the Cell to determine where each field begins and ends (note that the fields must be aligned on word boundaries -- where necessary, pad them out with fixed bits).

The test EvalProc hold the Test of the Subcircuit Design. It is a procedure which repeatedly: sets some inputs in the Cell's newIO, calls a procedure (Rosemary.Eval) to run the Cell, and compares the results in newIO with what it expected. Note that since communication is only through the Cell's newIO, this Test can be applied to both the Behavioral Description and the behavior engendered by the Structural Description (when expanded Nested).

The ports of a Class represent the Interface of the Subcircuit Design; each Port represents an Interface Item.

Clients of Rosemary make CellClasses known to Rosemary via calls on RegisterCellClass.

The ioTemplate is left over from the bad old days; ignore it.

This is how you get started. CreateTopCell is used to Instantiate the Root Subcircuit of a Circuit Design. That Subcircuit must have an empty Interface.

The ExpandDeciderClosure is the vehicle that communicates the user's decisions, for each Instance, about whether to use the Behavioral Description or the Structural one (and in what fashion). The DEFINITIONS module RoseHelp.Mesa provides two ways of making those decisions:

The first, ask, uses a button-pushing screen interface. When RoseHelpImpl.bcd is loaded and started, it creates a Viewer. The Viewer has slots for displaying the instanceName and className of the Instantiation under question. It has a slot for the decision. It starts out with a possible suggestion, which then may be edited. When a decision is being requested, a Button appears, which, when pushed, causes the decision currently being displayed to be used.

The second, DecideFromFile, reads the decisions from a file. The file should be a sentance of the language defined by the following grammar (with start symbol <cell>):

If the <decision> for a <cell> is elided, it is taken to be "L" (Leaf -- use the Behavioral Description).

The input to the Translator is a file whose extension is "Rose". It should contain a sentance in the language defined by the following grammar:

<id>s begin with a letter, and continue with letters and digits. Case is insignificant for keywords. <rope literal>s are enclosed in double quotes. <int literal>s consist of a string of digits. White space is insignificant, except that it it seperates tokens. Mesa-style comments are ignored, as well as text from Tioga nodes whose "Comment" property is TRUE.

Actually, the above grammar is a bit of a lie, in a couple of ways. First, the stuff from Mesa is treated a little oddly. It was decided not to try to actually parse Mesa. There are three ways of delimiting Mesa. In one, used by <default init expr> and <init data constructor>, a certain character (vertical bar) is used to mark the end of the Mesa source. That character can be included in the Mesa part by doubling it.

Another method for delimiting Mesa source uses Tioga's document structure. When one of the keywords that uses this style is encountered, the Mesa is taken to be the contents of all the children of the node containing the keyword. Also, the rest of that node (after the keyword) is ignored.

Finally, <signal type constructor> uses a very simple method: the Mesa is put in a <rope literal>.

The Translator actually parses this language by first using operator-precedance, then applying some further understanding to the resultant parse tree.

The translator produces from a ".Rose" file a ".Mesa" file (and some others). The ".Rose" file can contain descriptions of many CellClasses, and auxiallary PROCEDURES, TYPES, and so on. The ".Mesa" file will include calls on RegisterCellClass for all of the Classes from the ".Rose" file. The ".Mesa" file will also include ExpandProcs, IOCreators, Initializers, EvalProcs, and Ports's, constructed from the description in the ".Rose" file. The ".Mesa" file will include declarations for the TYPES of the state RECORD, and the initData RECORD. Actually, not all of these things are relevant for all Classes, and the Translator will not produce irrelevancies.

The <library> clause indicates uses of other CellClasses. Any CellClass used by a ".Rose" file, and defined outside that file, must be listed in a <library> clause. When a <cell instantiation> is processed, type checking is done. The <library> clauses tell where to look to get the information about those Classes necessary to do the checking.

The <imports> and <open> are there to allow for tweaking the Mesa that is produced; they add to the corresponding clauses in the resultant ".Mesa" file. Names mentioned in an <imports> or <open> clause are automatically added to the DIRECTORY clause of the Mesa, if necessary. The Translator starts out IMPORTing and OPENing Rosemary and IntTypes.

All three, <library>, <imports>, and <open> are additive and idempotent.

A <cedar> as a <main statement> introduces Cedar code into the output. A <cedar> that occurs before a <class> must contain only declarations. A <cedar> that occurs after all <class>es can contain declarations followed by statements.

A <class> is a description of a CellClass. The <interface> is the Interface of the Subcircuit Design. The Direction is encoded as follows: "<" means In, ">" means Out, and "=" means Both.

<signal type constructor>s work as follows. There is a Mesa interface (RoseTranslateTypes) through which one can associate with an <id> a SignalTypeConstructor. A SignalTypeConstructor is a procedure, which, given a parse tree for the arguments in the <signal type constructor>, returns an "understanding" of a SignalType. This "understanding" knows things like how many bits to allocate in an IO RECORD, the Mesa TYPE to declare such a field to be, the Mesa to produce that will compile into code to actually produce the desired SignalType, and a few other details needed by the Translator. When a <signal type constructor> ends with a tilde and <rope literal>, this means overriding the understanding's decision about the Mesa TYPE to declare the field of the IO RECORD to be. The <rope literal> contains the Mesa TYPE to use.

Currently there are two SignalTypeConstructors that get registered. One goes by the <id> INT. It takes one parameter, an integer, which specifies a bit width. The parameter can be omitted; it defaults to 1. It produces an understanding of IntTypes.IntType[n], where n is the integer parameter.

The other, which goes by the <id> Mnemonic, takes a single argument: a ROPE. It produces an understanding of Mnemonics.Mnemonic[r], where r is the parameter.

The <class part>s can appear in any order, but each should appear at most once.

An <init data> gives the body of a RECORD TYPE constructor. This is used in constructing the TYPE the ExpandProc and Initializer will expect for initData (the IOCreator will ignore its initData). The TYPE constructed will be a REF to such a RECORD.

Both <default init data> and <default init expr> provide defaults for the initData that will be passed such a Cell. They should not both be present, and it is possible to have neither. The <default init data> gives the values for the fields of the RECORD. The <default init expr> is any old expression which yields the right kind of REF.

In a way like that of the <init data>, the <state record> provides for the construction of a state RECORD TYPE. <initial valued state> is just like <state record>, except in the following way. When constructing an Initializer, the Translator, if given <initial valued state>, will initialize the state RECORD at the time of allocation, with code like "NEW [StateRec ← []]" (an ordinary <state record> gets only "NEW [StateRec]"). In order for this to get past the compiler, the fields given to <initial valued state> must all be given default values (with " ← expr" at the end). At most one of <state record> and <initial valued state> should be given. It is possible to give neither; EvalProcs are not required to keep state.

An <initializer> gives, verbatim, code to be used for the Initializer. It is put inside a Mesa <block> that OPENs the newIO, the initData, and the state (all NARROWed to the appropriate TYPEs).

An <eval proc> gives, verbatim, code to be used for the eval EvalProc. The Translator takes care of producing the code to copy from newIO into oldIO. The given code is put inside a Mesa <block> that OPENs the newIO and the state (NARROWed to the appropriate TYPEs).

A <test proc> gives, verbatim, the code to be used for the test EvalProc. The given code is put inside a Mesa <block> that OPENs the newIO.

An <expand> is used to construct an ExpandProc from. The <expand statement>s are processed in the order given; each produces code in the ExpandProc. A <cedar> simply gives code to be copied verbatim.

A <node instantiation> produces a Mesa declaration that introduces a Node. This is done by declaring a Node, and initializing it to the result of a call on CreateNode.

A <cell instantiation> produces a Mesa statement that instantiates a CellClass. The first <id> is the name of the Instance; the second names the Class. The <connection>s give the association between Ports of the Class and Nodes: the first <id> names the Port, and the second names the Node. The Translator checks that the Node and the Port were both declared to be of equivalent SignalTypes.

The optional <init data constructor> on a <cell instantiation> gives a Mesa expression to be given to CreateCell as the initData parameter. If none is given, but the Class being Instantiated has a <default init data> or <default init expr>, it will be used.

The translator registers two commands with the UserExec:

RoseTranslate <id>*

RoseUpdate <id>*

It is not necessary to use the Translator. Code can be produced by other means (including by hand) to implement CellClasses. Using the Translator, however, places some constraints on the Classes referred to from the ".Rose" source. Here is a summary of them:

Classes referred to in a ".Rose" source, but not defined there, must be made known to the Translator via a "LIBRARY" entry. For each <id> given there, there must be a file named "<id>.RoseSymbols". This file gives the information the Translator needs for those Classes. The format of the file should be:

The first <id> names a Class being described. The second is the name of the Mesa module that implements it. The <int literal> encodes a few random bits:

The <rope literal> gives a default expression for the Class's initData. If there is none, the <rope literal> is NIL.

The <interface> is the same as in a ".Rose" source.

If a RoseUpdate is to be done, there must also be a file named "<id>.RoseDeps". Its format should be

Each <id> in the first list will be recursively looked at in the manner we are discussing. The second list (if present) is taken to be all of the Mesa modules in the DIRECTORY clause of "<id>.Mesa" (if it exists), that is, all of the Mesa modules that this one depends on. This list will be used to decide (by looking at create dates) when to compile "<id>.Mesa", if it exists.

Finally, the ".RoseLoad" produced will reference "<id>.RoseLoad". It should contain UserExec commands to cause to be loaded and started, if not already loaded and started, the implementations of the Classes found in "<id>.RoseSymbols".

For an example of something that did not use the Translator, see RoseClocks, in section 5.

On an Instantiated Circuit, you can bring up Displays. A Display shows Instantiated Subcircuits, i.e. Cells, and Nodes. Displays are manipulated via Control Panels and Browsers.

In a Display, a Cell is shown as its instance name, followed by a colon, followed by an outlined rectangle which includes the display of everything that is a descendant of that Cell and is being displayed. If that Cell is a Real Cell, when it is in its Schedule, its instance name is displayed in an unusual manner. If it is at the head of the Schedule, it is displayed in video reverse. If it is elsewhere in the Schedule, it is displayed on a light gray background.

A Node is shown as its name, followed by one or two special characters, followed by a textual representation of the bits last sent out on its Distribution List. If there is only one special character after the Node's name, its meaning is as follows:

If there are two special characters, the first will be a colon. The immediatly enclosing Cell has been Instantiated in the Nested fashion, and this Node is the internal version of one of the interface nodes. The second character indicates the direction.

Rosemary allows for a user to manually cause bits to be distrubuted from a Node. The characters in the Tioga Viewer to the right of the Node's name may be edited. When the signal is given, the new text may be parsed into bits and distributed. The signal can be given via a Control Panel, or by hitting return. For convenience, clicking the Node's name with the Left mouse button will select the text in pending delete mode.

On any given Display, Browsers may be brought up. Browsers are used to control what is displayed. These browsers are built with a general Browser package. First a description of that package, and then a description of the Rosemary-dependant features of these Browsers.

The info parameter is what the Viewers package needs to create a Viewer. Actually, it is only necessary to set a few of the many fields in the ViewerRec. Setting the name is often nice. And you probably want it not to start out iconic.

On any given Instance of a Circuit Design, Control Panels may be brought up. Actually, Control Panels and Displays come together. Here is the procedure that creates them:

The Cell given to NewDisplay must be the Root. Nothing is returned for the Control Panel, as there is nothing to do with it (it is on the screen). The Display is returned so that it may be given to BrowseDisplay.

Control panels deal with things like Scheduling and running the simulator, distributing bits manually through Nodes, setting conditional breakpoints, and so on. Control Panels are RecordViewers, constructed by ViewRec. ViewRec.doc should be broughtover by Rosemary.df, and contains a description of the user interface presented by RecordViewers. What follows is a description of the meanings of the fields and procedures in a Control Panel.

stopBefore:, stopAfter: BOOLEAN

status: {Normal, Interrupted}

incrementalDisplay: BOOLEAN

Pack: PROCEDURE

NoticeEdits: PROCEDURE RETURNS [AOK: BOOLEAN]

NoticEditsAndRunIfOK: PROCEDURE RETURNS [AOK: BOOLEAN]

Run: PROCEDURE

SingleStep: PROCEDURE

Test: PROCEDURE [cellPathName: ROPE]

Interrupt: PROCEDURE

Proceed: PROCEDURE

Abort: PROCEDURE

ClearStack: PROCEDURE

ClearCondition: PROCEDURE

Or: PROCEDURE

PostCondition: PROCEDURE [name: SELECTED ROPE]

RemoveCondition: PROCEDURE [name: SELECTED ROPE]

PostIncremental: PROCEDURE [name: SELECTD ROPE]

RemoveIncremental: PROCEDURE [name: SELECTED ROPE]

AddNamedCondition: PROCEDURE [name: ROPE]

DeleteNamedCondition: PROCEDURE [name: ROPE]

Save: PROCEDURE [fileName: ROPE]

Restore: PROCEDURE [fileName: ROPE]

mode: {Value, Test}

conditions: READONLY SymbolTable

conditionStack: READONLY STACK OF Condition

condition: READONLY Condition

The Rosemary simulate-time user interface is Client-expandable. One case of this expansion has already been seen: the Viewer put up by RoseHelpImpl to ask for ExpandDecisions.

A more interesting place that expansion can occur is through the actions of CellClasses. A CellClass's Initializer may create a Viewer in which to interact with a user.

An example of this is the CellClass "ClockGen". The CellClass "ClockGen" is used for providing two phase clocking. It puts up a RecordViewer with the following fields: