Genesis2FAQ - StanfordVLSI/Genesis2 GitHub Wiki

Genesis2 Frequently Asked Questions... And Answers

YES!

Attached please find the Perl libraries that you need to run Genesis2. All you need to do is to

• Copy to your favorite location (e.g., $USER/bin/) and then do “tar -xjf PerlLibs.tar.bz2 -C PerlLibs”
• Since this is source code, please don’t put those libraries in a publicly accessible folder.

• In addition, in this link you will find a draft of my (Ofer Shacham's) thesis: (ask me for link by email). Chapter 3 is the high level description of the tool and why I created it. The appendix is written as a user manual. It contains installation instructions, all the commands etc. It also contain a couple of code examples (source is also attached here, with an example makefile).

• I still plan to work out some small demo based on your code but that might take a little longer. (unless by the time I get to do that you already tell me that everything is working perfectly ;-))

If you have any problems, please feel absolutely free to email or call me (xxx-xxx-xxxx). Any feedback would be greatly appreciated.

Ofer

I am now able to run the design examples of 'flop' and 'wallace' by following the README file and it successfully generates verilog files, but the "register file" example shows an error

  make: vcs: Command not found

when I type "make clean run" in that directory.

A. Vcs is the Sysnopsys simulator. I noticed that you have a Mentor flow that instead uses vlog to compile and vsim to run. Our Synopsys flow compiles with vcs and runs using simv. We have a new makefile example that supports the Mentor flow. To use it, you need to do:

 make clean run SIM_ENGINE=mentor

(i.e. add SIM_ENGINE=mentor to whatever make command you are using).

Meanwhile, if you just want to look at the Verilog use “make gen” (or better yet ”make clean gen”).

See What if I'm using Mentor Graphics tools? below.

We now have a makefile that supports mentor tools. You will still need to do whatever you are used to doing to get your mentor tools sourced to the environment of course. (You can do ‘which vlog’ and ‘which vsim’ on your linux shell to make sure that both these Mentor commands are in your path etc.)

Since the makefile now supports both environments, you need to do: ‘make clean run SIM_ENGINE=mentor’ (i.e. add SIM_ENGINE=mentor to whatever make command you are using).

Q. Can genesis produce the GUI (graphical user interface) for me automatically? I want a graphical user interface for the students in my advisor's class, so they can make experiments on my design. Is it possible/easy to do that?

A. Aha, excellent question. So remember, what we wanted to do was make it easier and standardize for people to make generators, right?

So with this in mind, we created the XML as genesis’ interface to the world, with a simple and standard schema. Our gui is completely independent of genesis---it reads the xml-out and draws that on the screen. It does not know (or care)if this is xml for a Pentium or an FFT. All it needs is to know the location of the source code (the .vp files). It then shows all the (hierarchically) and makes them available for users to tweak. It also shows the but does not let users tweak them.

You can see a couple of examples at http://www-vlsi.stanford.edu/ig/. Here is one:

* Click on “(Real-ish) CMP Generator.”

* Click on DUT and look for processors – there is only one and it is called p0.

* Click “up” (don’t hit the back arrow!)

* Change the number of processors to 3 and click on submit.

* Click on DUT.

* Now there are p0, p1 and p2 (there are also a bunch of other 
modules like I- and D-caches etc).

* Click on rf (register file). This is much like the regfile that 
I sent you in the example. You can now change its base address etc. 
Genesis will uniquify it and rename modules and files etc.

See http://genesis2.stanford.edu/mediawiki/index.php/InteractiveGenesis2GUI for more information on how to install and use the GUI on your own local machine.

A. Small tip: in many cases, a parameter is local to a module and does not change its interface. In these cases, it sometimes makes sense to add the parameter but to NOT bind it at instantiation (i.e. in the ‘generate’ call). When you do that, this parameter can be controlled from the outside by the XML configuration (and eventually by the gui).

(Of course, you can always just propagate the parameter to the top level and control it from there if you find that more convenient.)

I see.. Actually that's what I plan to do next: specify the parameter values from outside using the XML configuration. Did you do this in the example designs of "reg file" and "wallace"? Do I have to write the config.xml file myself? I generally don't know how to do it. When you run the code, it is able to read in the .xml files automatically and read in the parameters from .xml files?

A. Genesis optionally accepts an xml file as input for elaboration of the code. In the included makefile examples, it already does that. That’s the “-xml $(GENESIS_CFG_XML)” flag, and it reads config.xml by default. You can change the defaults by running e.g.

 make clean run SIM_ENGINE=mentor GENESIS_CFG_XML=YourOwnFile

Genesis knows how to parse the xml file and force the value of the parameters. However, note that the xml can only override a default parameter value. It cannot override a parameter that you have already overwritten in the generate statement upon instantiation. The reason is that we assume that if you decided to override the value at instantiation, you probably knew what you were doing, and might also have other code that assumes that value. So in summary, the overriding priorities are:

1. $self->define_param(PrmName =>PrmValue)  --- Lowest priority

2. XML input --- Can override define_param

3. generate(‘flop’, ‘pipestage7’, PrmName =>NewPrmValue) --- Can override both define_param and xml

4. $self->force_param(PrmName =>PrmValue) --- mutually exclusive with all other, 
and cannot be overridden in anyway (Advanced users: useful for exporting information 
from one module to another: module A uses force_param to declare something. 
Module B uses $A->get_param to read that. )

To make life easy and also to interact with the gui, genesis also dumps out (optional) a complete xml of the hierarchy. In the example makefiles these would be the “-hierarchy wallace.xml” for the wallace tree (I should probably fix that), and “-hierarchy $(GENESIS_HIERARCHY)” for the regfile. The output XML is a superset of the input xml because:

• For the input xml, you only need to specify modules that you care about and parameters that you want to override. The output XML contains all the modules and all the parameters. Whether override-able or not.
• The output XML contains a bunch of meta information regarding the source files, the source templates and the uniquified modules that were created. This info is not needed for the input xml.

Important note: I typically run genesis once to create the output xml so that I can use it as a template to create my input xml. You can also read more about the schema for both xml's at

 http://genesis2.stanford.edu/mediawiki/index.php/Genesis2#Program.xml_File 

and

 http://genesis2.stanford.edu/mediawiki/index.php/Genesis2#Hierarchy_Out

Finally, to your question:

In the Wallace tree, all parameters were bound at instantiation. In the regfile, I only bound the type of register but left the default value un-bound. As a result, when you run the elaboration, in the xml you will see (this is just a snippet of it of course) for register “DataIn_reg”, the following code:

      <DataIn_reg>
          <BaseModuleName>flop</basemodulename>

          <ImmutableParameters>
              <FLOP_TYPE>eflop</flop_type>
              <FLOP_WIDTH>32</flop_width>
          </immutableparameters>

          <InstanceName>DataIn_reg</instancename>

          <Parameters>
              <FLOP_DEFAULT>0</flop_default>
          </parameters>

          <SubInstances></subinstances>

          <UniqueModuleName>flop_unq4</uniquemodulename>
       </datain_reg>

Note that the ‘FLOP_DEFAULT’ param is the only one that is not bound, so genesis identifies it and puts it on the list. All other properties of the flop were bound at instantiation so those are on the list. This way I can (either manually or through the gui) tweak the value of each and every parameter individually. Makes sense?

Having said all that, I could have created a default value parameter for each flop at the top level and then propagate it to the flops through the code. Then those default values would have been immutable in the flop, but then they would be override-able at the top level (i.e. they would show up in the list at the <top></top> item of the XML.

I built a small and simple example of my own design "rotation.vp", which has only one parameter "INTER_ORDER", which can be either "BILINEAR" or "NEAR_NEIGHBOR". I wrote the source files (rotation.vp, top.vp and Makefile) by slightly modifying your "flop" design files. However, when I run it by typing "make clean run", it shows errors of "Genesis2::top: ERROR at (or right after) line 10 of file /*****/top.vp". I have attached my files; could you help me to look at what's wrong with my code? I wonder if there is anything else that I need to do besides preparing .vp files and Makefile?

I looked at your code. This was only a small issue of a couple of syntax errors in the Perl code. I do admit however that the error messages from genesis2 need to be improved significantly!

Instead of:

    //;  unless($flop_type = "BILINEAR" || $flop_type = "NEAR_NEIGHBOR")

Use:

    //;  unless($inter_order =~ m/^BILINEAR$/i || $inter_order =~ m/^NEAR_NEIGHBOR$/i);

Explanation: in Perl you can compare strings using the ‘eq’ operator (e.g.: if ($my_str eq “someString”)…, if ($my_str eq $your_str)…) . However, if you want to compare sub strings or regular expressions (e.g., in this case make it case insensitive) you typically use the ‘=~’ operator. So in the code above I made it compare to a regular expression: to return true, it must find a substring which starts with and end with ‘BILINEAR’ (this is what the ^ and $ sign doing-- ^ is line-start and $ is line-end). I also made it case insensitive using the ‘i’ like I show in the following answer.

  In "flop.vp",  

           //; if ($flop_type !~ m/constant/i) {........
  -------------
  what's the meaning of "~ m/constant/i" ? 

Perl is a scripting language that is all about regular expressions (i.e., string matching and manipulation).

 if ($flop_type =~ /constant/)
 * The “=~” evaluates TRUE if the string $flop_type matches (matches=has a substring) the string “constant”

 if ($flop_type =~ m/constant/)
 * The “m” is optional; it means "match" the indicated expression.
   All regular expressions enclosed in slash-marks are "m" by default.

 if ($flop_type =~ m/constant/i)
 * The “i” at the end makes it case insensitive (would match constant, consTANt,  CONSTANT, etc.)

 if ($flop_type !~ m/constant/i)
 * The “!~” means the opposite of “=~”. That is, expression is true
   if the string $flop_type DOES NOT match the string “constant”

A very concise and easily readable tutorial on perl regular expressions is here:

• http://www.troubleshooters.com/codecorn/littperl/perlreg.htm

In "top_flop_only.vp"

       //; my $const_flop_obj = generate('flop', 'const_flop_eg', FLOP_TYPE=>'constant',
       //;                               FLOP_DEFAULT => 0xFF, FLOP_WIDTH => 32);
       `$const_flop_obj->instantiate()` (...);

what are "const_flop_obj", "flop", "const_flop_eg" mapping to?  
I thought "const_flop_eg" is the inst name, but when I look at 
the generated verilog file, the module name is "module flop_unq1". 
I wonder where you specify the name of "flop_unq1" or if it must 
be in this format?''

A. Every module that is generated is an object (in this case “$const_flop_obj”). This object is a sub-instance of the parent module. That is, in this case “$const_flop_obj” is a son/submodule of top. The base module name is ‘flop’, but you may end up generating many different flops, right? So we need to give each of the generated ‘flop’ modules a unique module name (similar to the work you had to do in your code manually. For example to create different “ftype"_twi_rom_"i”). Genesis2 does this for you. It checks if this is a new (and different) ‘flop’ and it names the module ‘flop_unq#N’. Does this makes sense? Of course, the flop object (in our case “$const_flop_obj”) knows what unique module it is and “$const_flop_obj->get_module_name” will return that value.

The second argument is the name of the Verilog instance. The name of that instance (when Verilog is generated) is ‘const_flop_eg’. This means that we expect that when the Verilog for top.v be generated it would have a sub instance of type ‘flop’, but uniquified so let’s call it ‘flop_unq132’ and by the name ‘const_flop_eg’.

The generated code should look something like this:

    flop_unq132 const_flop_eg (…)

    endmodule

Does this makes sense?