SSHAFT Tutorial #1

Introduction to writing scripts in the SSHAFT framework

SSHAFT is the System to Silicon Hierarchical Flow Tool. It is an API that exists primarily in Perl and SKILL that allows creation of a robust design flow, handing off control between the two.

1. Create a run directory for this tutorial.
2. Copy the file descend.pl into this directory. The file is a normal perl script that uses the SSHAFT API (as indicated by the use commands near the top. There SSHAFT API calls are the ones that you may not recognize:
   • beginstep - This declares that this program is a "step" in a larger design flow and gives its name.
   • logf - The basic logging function. It operates like the print or printf command in most languages, except that its first argument is the "level" or "severity" of the log message, which is used to filter out log messages when logs get too large.
   • dief - like the PERL die procedure, this procedure prints an error message to the log and halts execution. Note that no log-level is needed, since it will always be LOG_ERROR.
   • substep - like the system procedure, this invokes another PERL script. The first argument is the mode, which states that the program to be invoked will be a UNIX command, and that it is also a "step", like this one, written in the SSHAFT API. The second argument is the command-line string.
   • endstep - This declares the end of the step and exits the PERL script
   This program recursively calls itself (using it's first argument to count the invocations), until a maximum depth is reached. The program prints a log message during each invocation, and gives an error when it reaches the point of deepest descent. The log message that reads "This point will never be reached", is not printed, because dief halts the execution.
3. Execute the following command: descend.pl 4
   Now we see the logging functions at work. Note that each invocation is indented. The substep procedure prints the log messages that start with "Executing:" to show the complete command-line string, for reference. Note that a number of extra arguments have been added ("-ll", "-li", etc.). These arguments are used to make sure that the indenting and filtering work properly. Note also that each invocation begins and ends with "Begin descend.pl" and "Terminated descend.pl". These are written by the beginstep and dief procedures.
4. Execute the following command: descend.pl 4 -log flow.log
   Note that nothing is written to STDOUT, but all log messages are written into flow.log in the correct order. The "-log" and "flow.log" arguments are special arguments that are removed from the argument list by the beginstep function. Note that the order of these special arguments does not matter, and "descend.pl -log flow.log 4" works exactly the same.
   
5. Execute the following command: descend.pl 4 -log flow.log -tol high
   The "-tol high" arguments run in high-tolerance mode, which means that a failing substep will not halt execution of the larger flow. This is helpful in debugging, if you want to test something later on in the flow but don't want an error early on to keep you from reaching that point. The effect is that we see the message "This point is never reached" now written to the log file. Also note that the last entry of each invocation in the log file reads "Finished" instead of "Terminated", as before. This is because the step is being exited with the endstep function, rather than the dief functin.
6. We're done with descend.pl. Next, copy the files synth.pl and addreg_behav.v into your run directory. Look at the synth.pl script. You'll notice that it has the following parts:
   • Argument parsing - The arguments -mod, -file, -lib, -per, and -clk are taken from the command-line arguments. A default value for $lib is given as "mylib"
   • Synthesis - Design Compiler is executed with a script generated by synth.pl
   • Library Creation - A SKILL function called wrdCreateLibrary is called to create the library
   • Import Verilog - The ihdl program is invoked to import the Verilog netlist, using a parameter file dumped by the synth.pl script.
7. Execute the following command: synth.pl -mod addreg -file addreg_behav.v -per 900 -clk clock -log flow.log
   You should find that the synth.pl script exits with the message "ERROR: dc_shell did not run successfully, See run/dc/synth.log for details". What went wrong? To find out, Error, look in the file run/dc/synth.log, as directed. Find the line that starts with "Error:". You should see the following:
   create_clock -period 900 clock
   Warning: Can't find object 'clock' in design 'addreg'. (UID-95)
   Error: Design object list required for the '<port_pin_list>' argument. (EQN-19)
   This means that the clock node has been named incorrectly. Look in the file addreg_behav.v and you will find that the clock node is actually called CLK.
8. Now, we'll fix this problem by specifying the node "CLK" instead of "clock". Execute the command
   synth.pl -mod addreg -file addreg_behav.v -per 900 -clk CLK -log flow.log
   Everything should be working fine now. You can see the timing report in run/dc/timing.rpt, or you can go to the run/cds directory, start Cadence, and look at the schematic that was imported.