1. Introduction
What you need to know before starting
You should be familiar with ChipnDale, Sisyph, and Rosemary. Understand icons, structured wires, satellites, ... If the documentation is not sufficient, complain to the author/maintainer.
For composite wires, you should know about the generators put out by Bertrand Serlet (see above). P-middle is the commands to access Composer, Extractor, Range Extractor, and Bus Constructor. As usual, 0 is the high-order bit (wire) and is indicated by an extra-wide pin in the composer. Never, never, never, attempt to edit such icons.
Simulation
For large simulations involving a simulation proc and a test proc, refer to the Rosemary documentation (available only in Basque and Southern Mongolian through Rick Barth, Unlimited Doc. Inc., rm 2218).
For interactive simulation, build a cell including the cell(s) to be tested with testing paraphernalia (roseClock.icon among them). Vdd and Gnd get their value automatically. Beware that the three logic level L, X, and H are used, and that all states are initialized to X.
Which wires do you want to display? Here are the possibilities:
- Every top-level named wires (i.e. part of the internal wire of the top cell) will be displayed. A wire is named if you name it explicitely or if the inherited names do not conflict.
- Using the add command in the Rosemary typescript, you can add to the timing display (oscilloscope) any wire which you can access by name. Familiarity with the commands available in the Rosemary typescript and long-name syntax will help a lot.
Now you can simulate at two different levels. Most macros come with a behavioral procedure which tries hard to reproduce reality, and a decomposition in more primitive cells. The behavioral model of basic cells has been checked and can be reasonably be trusted. The default uses only the basic cells: it is thus slow but quite precise. If you are worried about speed, you can add in the simulation cell an object satellite [Simulation: $Fast] to use top-level behavioral procedures: faster, but not as safe.
Then call "Sisyph Extract and Rosemary" in the SPACE-O menu; your cell will be extracted, Rosemary will create a simulation and a display panel with a typescript and an oscilloscope-like display. If instead you get an error window with no message on the terminal, come and complain for this should not happen.
Start the simulation by bugging "Single Eval" and watch the values on the ports change; for faster action, use "Proceed" and "Interrupt".
Clock generator
By use of sufficiently advanced technology (i.e. magic) the following notion of time is provided: everytime you bug the "single eval" button in the Rosemary panel, the time is incremented by 1.
The clock generator roseClock has access to this "time". It accepts four parameters: up, dn, firstEdge (all integers expressed in time units), and initLow, a boolean specifying the initial state of the clock. The defaults (up ← dn ← firstEdge ← 1; initLow← TRUE) provide a simple tick-tack generator: starting in a low state, it alternates between H and L everytime you bug the "single eval" button.
How to reach infinity: if you need to specify a single pulse and would like to say dn ← infinity, you can use the value LAST[INT] (=2147483647 cycles, which looks like a very long simulation), or by convention -1 will have the same effect.
Oracle
The oracle is a test procedure that is particularly useful for testing simple blocks without coding. It has three required parameters, an input bus (in), an output bus (out), and the name of the file containing test vectors (id). The Oracle's default behavior is to stop the first time it finds an error; however, if a fourth optional parameter (log) is used, the Oracle records errors and continues.
Oracle: Computational Model
On the rising edge of the oracle clock, the oracle does two things, in the order given: (1) it advances to the next line of the test vector file; and (2) it drives its outputs to values that appear on the left hand side of this line. These values stay on the output wires of the oracle till the next rising edge of the oracle clock, at which point the outputs are driven to values specified by the following line.
On the falling edge of the oracle clock, the oracle compares the values on its input wires with the values specified on the right hand side of the current line. If there is disagreement, it signals this, typically causing the simulation to enter the debugger.
Oracle: Parameters
Here are definitions for the four oracle parameters:
id: The name is used to find the default file name (id) or (id).oracle and to generate a log file as ///Temp/(id).bugs if you use the log feature.
log: If set, the log parameter will cause the oracle to dump all errors found during simulation (not during parsing) in a file ///Temp/(id).bugs instead of signaling every mismatch. This option is turned off by default.
in, out: The input and output wires are structured, and you must specify the structure of subwires by listing the size of every component. By convention, an atomic wire has size 0, while a single-element composite wires (a rare beast) has size 1. If a wire has more structure, you enclose the structure of its subwires in a pair of (), recursively without restriction on the depth of wires.
Example:
out ← "0 8 (0 32)" -- a bit, a byte, and a 32-bit bus with its parity
in ← "0 4" -- a bit and a nibble
Oracle: Standard Semantics for Files of Test Vectors
Stimuli and expected results are stored in a file, one line per "clock cycle". This means that if the circuit under test has a single stage of delay (for example a D flop), the right-hand side of a given line corresponds to the outputs that should appear if the left-hand side of the previous line were placed on the inputs one cycle earlier. Thus, the oracle file for a D flop should have the following test vectors:
0 | x
1 | 0
0 | 1
0 | 0
1 | 0
x | 1. (Fixed-pitch fonts were invented for this purpose. )
And, if the test circuit has two stages of delay, then the right hand side corresponds to the input two lines earlier, etc.
Here is a example of a more complex test vector:
1 FF ( 0 FF03 ) | 1 00FF
Notice the () with spaces around them match the wire description. Now, in a case where we don't care about the single-bit wire in the result, it could be:
1 FF ( 0 FF03 ) | X 00FF
And if we want to tristate the low-order bit of the second input wire, it would be:
1 F(111X) ( 0 FF03 ) | X 00FF
Now the syntax:
Value ::= SimpleValue | StructuredValue
SimpleValue ::= Digit ?Digit
StructuredValue ::= ( Value ?Value )
Digit ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | A | B | C | D | E | F | X | ExpandedDigit
ExpandedDigit ::= (Level Level Level Level)
Level ::= 0 | 1 | X
Values will be converted to a sequence of levels, zero-extended, and distributed on the corresponding wire. Simple values are specified by hex digits (including X) such as 0, 1, 35, 4FFA and X022XX. Any hex digit can also be specified as four bits exactly in a pair of (), as in (0011), (001X) or (XX0X): no space inside a value! To specify the values for a deeply structured wire, use parentheses and spaces. Don't forget the spaces or the parser will get confused.
For inputs, an X on a wire means don't care; for outputs, it means tristate.
The file is read every time you click the Start button in Rosemary, so you can modify it without re-extracting. The name of this file is defaulted to (id) or (id).oracle, but you can change it with
← Logic.SetOracleFileName["TheIdName", "NewFileName"]
and if you are confused as to which file name is currently used, type
← Logic.GetOracleFileName["TheIdName"]
The Oracle: Dual Clock Method For Standard Semantics
For most circuits built using items in SCLogic, using a single clock for both oracle and circuit might work, especially if the circuits are at transistor level. However, problems arise when the test circuit has a behavioral proc. Because the single clock method does have problems, the dual clocking scheme, using one clock for the oracle and one for the circuit is recommended.
The oracle clock should have the parameters <up𡤂, dn𡤂, firstEdge𡤂>. The circuit clock should have the parameters <up𡤂, dn𡤂>. Using these parameters causes the oracle clock to be a quarter cycle delayed with respect to the circuit clock. Thus, the order of events in a given cycle is:
- circuit clock rising edge (circuit samples values just before edge and computes its outputs)
- oracle clock rising edge (oracle goes to new line and places left hand side on circuit inputs)
- circuit clock falling edge
- oracle clock falling edge (oracle checks circuit output against right hand side)
Assertion verification
The icon roseStop has the property that if its input (anywhere on its periphery) is high, then it raises a Rosemary signal. When the Event Window opens, it is possible to update the display by bugging the Update button. One can also proceed by bugging Proceed in the Event Window (not in the Rosemary panel).
Due to the algorithm used by Rosemary, non-race-free circuits can generate glitches which could raise the signal though the final value after the simulation settles would not. To avoid this, the input is sampled on the next Time transition.
Cosmetics
A family of arrows is provided. These arrows are strictly cosmetic and ignored by the extractor.
A contact cell is also provided: it is useful to indicate connections among crossing wires without having to break these wires.
Power supply
For historical reasons, there are two sets of Vdd and Gnd icons: they are now equivalent. The cells providing logic 0 and 1 are automatically inserted by the SC layout system, so don't worry about how many such symbols you use.
The Static checker
It is a good idea to run Static, the static checker, on your design. In order to avoid false errors, mark every unconnected output (for example the complementary output of a register that you do not use) with the unconnected icon, a little black square.