IEEE 200X Fast Track Change Proposal

ID:      FT-32  Unification of PathName and Instance Name for PSL, VHPI, and VHDL


Status:       Proposed
Proposed:     John Shields
Analyzed:     John Shields (from meeting discussion on 6/6/05 
                            edited into proposal format by Jim Lewis)
Resolved:     Date


Relevant LRM sections:   



Enhancement/Requirements Summary:
============================================================
Formulate a common notation for path [and instance] names
within VHDL for use by PSL, VHPI and VHDL hierarchical reference


Summary:
Proposal puts forward formats for paths as follows:
  Path specified from design root (elaborated):
    .<name>.<name>...

  Path specified relative to an elaborated package:
    @<lib_name>.<pkg_name>.<name>....

  Path specified relative to a compiled, but unelaborated design unit:
    !<lib_name>.<design_unit_name>.<name>....

  Path specified relative to some reference context:
    <name>.<name>...

  Going upscope (presented with options):
    ..<name>.<name>...   -- concern over distance from '.' and 
                         -- how go up 2  
    ^<name>.<name>...    -- an alternative 

Proposal also creates a new attribute, full_name that will return
a value in the above format.  


See also:  
Peter Ashenden Analysis:
   http://www.eda.org/vhdl-200x/vhdl-200x-ft/proposals/ft32_pathname.pdf


Roll-up of reflector discussion on pathname:
  http://www.eda.org/vhdl-200x/vhdl-200x-ft/proposals/ft32_pathname_issue_rollup.html 



Enhancement Details
============================================================


Complete Pathnames
----------------------------------------------------
By complete pathname, I mean a unique canonical name that is not
relative to some other object. VHPI already has a definition that
addresses the shortcomings of `pathname. It draws on the current
definition but has modified the syntax to address ambiguities. It also
deals with the need to refer to objects in the design hierarchy(the
instantiated information model) as well as references to objects in
compiled design units in libraries (the uninstantiated model). VHPI
calls it the fullname. PSL has a definition for pathnames that
overlaps the VHPI definition for references to objects in the design
hierarchy. There is a key conflict in the syntax of the VHPI and PSL
definitions in the legal characters to use for a prefix and
hierarchical separator. The signal spy proposal is incomplete and
aligned to VHPI and `pathname syntax already. I presume it will 
happily follow the same syntax as VHPI uses.

PSL allows either '.' or '/', but cannot allow ':' because of language
interoperability conflicts with Verilog in mixed designs. 


VHPI currently uses the following formats:
  Objects in the design hierarchy, VHPI chose
    :<name>:<name>:.. 

  objects in elaborated packages, VHPI chose:
    @<lib_name>:<pkg_name>:<name>:... 

  objects in compiled design units, VHPI chose:
    @<lib_name>.<du_name>.<name>.<name>... 


I propose first to accept the PSL syntax constraints and modify VHPI
so as not to conflict with it. Either '.' or '/' are possible to use
as the hierarchical separator. I choose '.' and to guarantee that
the remaining syntax needed by VHPI will not conflict if '/' is used
as a separator. I further propose to use the '.' separator uniformly
as a separator and chose 2 different prefix characters to refer to
elaborated packages and compiled design units. '@' will refer to
elaborated packages and '!' will refer to objects in compiled design
units. 

The new syntax is roughly:

  objects in the design hierarchy:
    .<name>.<name>... 

  objects in elaborated packages:
    @<lib_name>.<pkg_name>.<name>....

  objects in compiled design units:
    !<lib_name>.<du_name>.<name>.<name>... 


I think this is simple and consistent. It certainly affects VHPI and
leaves PSL alone. You may prefer other choices for syntactic sugar,
but this is the framework for one solution.



Wildcard Pathnames used in PSL
----------------------------------------------------
This is really a way to refer to a set of complete pathnames of
interest to PSL. PSL binds vunits to design unit instances in the
design hierarchy. You can specify a design unit instance by complete
pathname or using a wildcard. The wildcard refers to a design unit in
a library by name to imply a reference to the set of all instances of
that design unit in the design hierarchy. The PSL binding currently
refers to design unit by either its entity name or to the name of an
entity/architecture name pair. The lack of a library qualifier is a
known limitation in the current PSL binding. PSL would refer to an
entity as entity_name or entity_name(architecture_name). 

I would propose to unify the syntax of PSL and VHPI references to 
design units in a library. This amounts to extending the PSL syntax 
to support an optional library qualifier such that wildcards are now:
  [!<lib_name>.]<entity_name>[(architecture _name)]


In VHPI (where it may apply), I think the syntax for referencing
secondary units should use the optional secondary name in parentheses.
I thought it did, but someone disputed that and I haven't checked it.
It definitely should not use a ':' or '.' separator as if it were an
additional lexical or hierarchical name scope.

As a final sidebar, PSL does allow the wildcard to be further
qualified by a relative pathname appended to the wildcard. This is a
reference to a sub instance of any instance of that design entity.
There is nothing in conflict with VHPI syntax here. Indeed, VHPI
supports relative name references. In my proposal, the
relative name reference syntax is consistent for VHPI and PSL


Relative Pathnames
----------------------------------------------------
I mentioned that VHPI uses relative names. It is possible to
refer to or obtain a handle to an object by using a relative pathname
and a reference context. The relative name syntax has no leading
prefix character. With my proposed change to VHPI syntax, a relative
path is of the form:

  <name>.<name>... 


In VHPI, the reference context is a handle to an instance in
the design hierarchy, elaborated package, or a compiled design unit.
(I've slightly oversimplified it). The relative reference is strictly
downward from the reference context. This is a straightforward model
that can be extended, but we have kept it intentionally simple.


There are additional needs for relative references in 200x for signal
spy. The need is for an explicit upwards relative reference. A
nice syntax in the UNIX file system is ".." as in ../foo/bar. I
prefer the idea of adding a syntax for explicit upward reference to
the VHPI relative pathname. Having chosen the '.' as a hierarchical
separator, another lexical token besides '..' would be prudent. Could
we use '^' or "<-", "%up%", etc.? Maybe it would make more sense to
revisit the hierarchical separator and use '/'? This opens up the use
of the UNIX pathname syntax as a model for all absolute and relative
references to VHDL hierarchical structure.


This is an open issue; the syntax needs to be resolved. 
It is desirable to use '.' to gain consistency with verilog
and, hence, perhaps have consistency in mixed HDL designs.


There is no requirement that I am aware of for the use of a wildcard
in a relative pathname that means "anywhere below this point of
reference" such as /top/foo/.../bar. On the other hand, I understand
that systemverilog has found a use for it :) Seriously, this can be
anticipated as a possible need and we should reserve a syntax for it.


Relative searching by name
----------------------------------------------------
There is no requirement for this that I am aware of, but it is
something supported by Verilog in its hierarchical name reference
model. The idea is that, given a relative path name and a current
reference context, look downward for it, then start the search in the
next enclosing scope and continue to recurse outward until you find it
or exhaust the search. I may not fairly describe the Verilog rules,
but the point is, "Is this useful?" Furthermore, does it need to be
considered for signal spy or is it already? I don't make any proposal
here. My opinion is that it seems ill considered and leads to false
references where the intended search really failed. Where it is
important, I would like to just capture the use case.


Fix `pathname or create a new attribute?
----------------------------------------------------
It makes sense that one can print out the name of an object
that corresponds to the name that can be used to refer to it. 
VHPI supports a string property tagged vhpiFullName for 
that purpose. We did not add an attribute to the language for
printing it from models. We do acknowledge that `pathname and
`instname exist in the language and we allow that name to be retrieved
as string properties in VHPI. We have asked 200x to consider whether
these properties should be fixed to further unify the language and
VHPI.

This was discussed and that may continue. The 200x folk seem
to agree that breaking backward compatibility will not be acceptable.
User will not want to change their legacy source code and a runtime
switch to get either 200x or pre 200x `pathnames may not fly. A new
attribute is therefore a good idea, but the caution is to choose a
good name and not create confusion. So, for example, pathname2 and
path_name are bad choices. I propose `fullname.

I do understand the significance of `instname and one may also want
`fullinstname. (VHDL-AMS may indeed care.) Regardless, I prefer to
stop short of that for now.


Niggling Details?
----------------------------------------------------
I'm sure there are a few centered around the details in the
VHPI definition. We define an algorithm for naming unamed processes
and loops. There is some confusion and or concern about the names of
dynamically elaborated objects, e.g., locals with a nested subp
calling sequence. Overloaded names and signatures. Pathological
cases where there still is no unambiguous name for some object. 

The principles VHPI strove for are 
1) attempt to define unambiguous references for everything important,
2) accept a minimal form of the name that is unambiguous for lookup 
3) treat the pathological bad cases where ambiguity remains as
   self-inflicted wounds! 

We did not completely achieve those goals, but
pretty close. One misunderstanding I've seen is that VHPI requires
signatures to refer to overloadable objects. The signature can be
left off if there is no ambiguity. If you ask for the fullname
however, signatures are presented.

I propose we leave the niggling details until we agree on the larger
issues. The we is PSL, VHPI, and 200x working group members.



============================================================
============================================================
============================================================


Analysis
============================================================