IMPORT Guidelines For e, Part 1

[Team Specman welcomes AE Manager Avi Behar as our newest guest blogger]

Hi, my name is Avi Behar and for the past eight years I’ve been supporting Specman users from Allentown to Yokohama (any Specmaniacs at a location starting with "Z"?  I’m coming!).  If you are reading this and have been using Specman, my guess is that somewhere along the way you’ve had issues with controlling the order in which your e files are imported into the tool.  Here’s why:

1. e is an Aspect Oriented Programming (AOP) language; in the context of the file load ordering this has two main implications: 

1.1. You can basically extend / overwrite any struct member, making the order that these extensions/overwrites are loaded signifigant

1.2. Quite often you will have files implement functionality (an aspect) across a few units and structs (objects), making these files dependant on the code contained in previously loaded files (see next point).


2. In your code you can only reference units/structs in files that will be loaded into Specman before the file you are currently developing (for example call methods, extend or overwrite struct members).  This imposes the linear file-loading order on the way your code should be organized.


3. Last but not least, there are no well defined guidelines on how to control the file load order, with the exception that eRM / OVM e recommends you solve inter-file dependencies by either:

3.1. Using cyclic imports (i.e. file "a" imports file "b" and vice-versa)

3.2. Defining referenced units/structs in header files


Lacking clear guidelines for choosing between [3.1] and [3.2], many new users follow the C paradigm of “each file imports the files it relies on”.  This together with the (ill fated, IMHO) cyclic import recommendation [3.1] and the AOP nature of e code [1.1] quickly creates very complex import graphs where many files cross-import.  It is very difficult to impose a linear path through this graph [2] resulting in a trial and error approach to commenting import declarations in various files until at last the frustrated user finds a delicate equilibrium that only lasts until someone else, potentially on the other side of the Earth, tries to update/reuse the code, shattering the porcelain equilibrium and while the original developer, sinks into despair.  To summarize, it is the combination of these factors that is both the top reason why controlling the import order is very important when using Specman, and why many new users make a mess of it.

Consequently, the approach I’ve been advocating with my customers is to stick as much as possible to a single file, linear, load-order control approach focusing on the _top.e file.  Along the way I try to make easier the use of a truly fantastic Specman feature – the ability to combine compiled code (for better performance) with interpreted code (for a faster debug cycle). This is done using the _compile_base file.

The compile_base file should import all the files we wish to compile from the very beginning of our project, including:

* eVCs/UVCs, the Register Package (a/k/a "vr_ad"), legacy code by other users.

* Any defines required by these packages at the time of compilation, for example: VR_AXI_USE_INTELLIGEN, VR_AD_ADDRESS_WIDTH

* Extensions to prj_env_name_t / evc_name_t enumerated types so we can add instance specific implementation (for example, scoreboarding) in the user code that will be imported from the *_top file

* Additionally: as code gets stable move it from the *_top file to the *_compile_base file!

Here is a generic example.  First, consider the following "top.e" file:

*_top.e
Import *_compile_base;
Import *_types;
Import *_env_h;
Import *_slave;
Import *_master;
     .
     .
Import *_env;

Next, here is an example of the corresponding "compile_base" file listed above:

*_compile_base.e
define VR_AD_ADDRESS_WIDTH 64;
define VR_AXI_USING_INTELLIGEN;
Import vr_ad/e/vr_ad_top;
Import vr_axi/e/vr_axi_top;
Import vr_pcie/e/vr_pcie_top;
extend vr_axi_env_name_t :[MY_AXI];
extend vr_pcie_env_name : [MY_PCIE];

Two notes about this:
* Usually the defines required by eVCs are set in the eVC’s config file.  As these are not usually reused “as is” we are not including them in the files imported by the compile_base file.  But we do need to include the defines at the time of compilation so we should comment out the defines in the config file (to avoid an “already defined” error when loading the config file) and set them up in the compile_base file instead (before the importing
the evc_top file).

* In most cases we can wait with extending the name enumerated types until we load the config / sve files, but if we are extending a generic eVC with design specific code we should do it under the specific instantiation of the eVC that we will have in our SVE file, thus extending these enumerated types in the compile_base file before loading our design specific extensions to the eVC code.

In a follow-on article, I'll talk a little bit more about setting up a good top.e to further avoid cyclical imports, and to smoothly handle patches and temporary work-arounds.

Happy importing!

Avi