Produces fresh names for a module.
This is a product type introduced by defprod.
The following invariant is enforced on the fields:
(vl-namefactory-namedb-okp mod namedb)
A name factory allows you to easily and efficiently generate good, fresh names that are not being used elsewhere in a Verilog module. They combine a name database (which is a general mechanism for generating fresh names; see vl-namedb-p for details) with a Verilog module in order to avoid computing the module's namespace until a name is actually needed. This optimization often saves a lot of consing.
Typically, given some module
Once constructed, name factories must be used in a single-threaded
discipline. That is, the functions for generating names actually return
Two functions are provided for generating names:
We use these functions for different purposes. We think that vl-namefactory-indexed-name should be used for "throwaway" names that don't need to be reliable or understandable, such as the names of temporary wires to be generated for split-up expressions. Meanwhile, vl-namefactory-plain-name should be used for splitting up instance names or in any other cases where a reliable name is desired.
Because name factories make use of fast alists, they should be destroyed
To establish that name factories generate only fresh names, we introduce the
Together, these theorems ensure that, when properly used, the name factory will only give you fresh names.
Name generation is a surprisingly important and difficult problem. It needs to be very efficient: we have sometimes found that tens of thousands of fresh names are needed, e.g., in split. Toward this goal, our original approach was as follows:
This scheme was highly efficient because the module's namespace only needed to be consulted when generating the first wire's name. This meant that for large modules, generating thousands of names was not very expensive. It also meant that if no fresh names were needed, then the module's namespace was never even computed.
But a problem with this scheme is that the generated names are not very good or predictable. This was particularly problematic when instance arrays like:
basic_flop data [(width - 1):0] (q, ph1, d);
would be transformed into something like:
basic_flop _gen_19 (q, ph1, d); basic_flop _gen_18 (q, ph1, d); basic_flop _gen_17 (q, ph1, d);
that is, here the instance name
Name factories basically extend this scheme to allow much better names to be generated, while still being quite efficient.
A name factory has two fields:
The invariant we maintain is that either the namedb is empty, or every name
in the vl-module->modnamespace of