Hierarchical Libraries

Proposal Details

Current Situation

Packages and entities may be compiled into libraries. The library hierarchy is flat, ie. libraries cannot contain other libraries.


Change VHDL to permit arbitrary levels of hierarchy in namespaces and to allow local renaming of namespaces.

  • Support Hierarchical Libraries of the form: library protocol.packet.ethernet;
  • support short hand names for libraries: library protocol.packet.ethernet as ethernet;

Implementation details

Library hierarchy is defined by . separator characters.

We support two mechanisms for creating library hierarchy:

  • Entities and packages can define a name containing an arbitrary number of hierarchy separators.
  • Alternatively, a package may be compiled into an arbitrary library structure containing hierarchy separators.

Code Examples

Defining a hierarchical package (ADA95 syntax):

package packet.ethernet.constants is
    constant MAXIMUM_PACKET_LENGTH : integer := 1500;
end packet.ethernet.constants;


Compiling a flat package into a hierarchical library:

vcom -work protocol.packet.ethernet constants.vhd

Using the hierarchical library:

library protocol.packet.ethernet;
use protocol.packet.ethernet.constants.MAXIMUM_PACKET_LENGTH;

Maintain the library independence usage with work. -- JimLewis - 2011-07-14

  • The language defines work as a short hand name (alias) for the library into which we are currently compiling.
  • From the top-level, I may reference a package as:
library Chip1.packet.ethernet ; 
use Chip1.packet.ethernet.constants.all ; 
  • From within Chip1, I would reference the same package as:
library work.packet.ethernet ; 
use work.packet.ethernet.constants.all ; 
  • From within the packet library I would reference the same package as:
library work.ethernet ; 
use work.ethernet.constants.all ; 

How do we rename, or create a short hand name for a hierarchical library (3 alternatives below):

  • Renaming (short hand name for) a hierarchical library locally (Extend VHDL Aliases): -- JimLewis - 2011-07-14
alias ethernet is protocol.packet.ethernet ;
-- ?? overuse of alias?
library ethernet ; 
  • Renaming a hierarchical library locally (ADA95 syntax):
library protocol.packet.ethernet;
package ethernet renames protocol.packet.ethernet;  
-- ?? Is this example for hierarchical packages?    -- Main.JimLewis - 2011-07-14
-- ?? Is this also for lib names?
use ethernet.constants.MAXIMUM_PACKET_LENGTH;

  • Renaming a hierarchical library locally (Pythonic syntax):
library protocol.packet.ethernet as ethernet;
use ethernet.constants.MAXIMUM_PACKET_LENGTH;

Direct entity instantiations: -- DanielKho - 2011-07-01

i_block0: entity protocol.packet.ethernet.mac(rtl) port map(...);

Configurations: -- DanielKho - 2011-07-01

configuration top_level of design is
   for structural
      for c_mac: mac
         use entity protocol.packet.ethernet.mac(rtl);
         for structural
            for c_xgmii: xgmiiTx
               use entity protocol.packet.ethernet.mac.xgmiiTx(rtl);
            end for;
         end for;
      end for;
   end for;
end configuration top_level;

Use Cases

To take a pertinent example let us consider libv, a library of useful functions for VHDL. At the time of writing, libv is a package named libv containing 5 functions and 3 procedures in the same package.

You might use libv in this manner: use work.libv.str;

Let's imagine that suddenly hundreds of people contribute multiple functions to add to this package. It would become necessary to split out into multiple packages, perhaps a package for string manipulation, a package for file IO, a package for asserts etc.

Then you might compile all these packages into a libv library: use libv.asserts.assert_equal;

Then things really start taking off and people contribute entities to libv. Now you need some way of segregating your namespace because the library libv is quickly becoming cluttered with a mixture of synthesisable entities, handy testbench functions, useful type definitions etc. Hierarchical namespaces are the answer: library libv.entities.peripherals.i2c;

Arguments FOR

  • ADA 95 added support for hierarchical namespaces
  • Flat library creates serious limitations
    • Project become larger requiring improved namespace management
    • Difficulty ensuring thirdparty libraries integrate together
  • Library structure cannot match directory structure
  • A simple and logical tweak to the language to bring inline

Arguments AGAINST

General Comments

I went and rexamined the Anotated Ada Reference Manual '95 to reinforce my understanding of Ada library hierarchy. The arguments for Hierarchical Named spaces in libraries should be examined:

  • ADA 95 added support for hierarchical namespaces

There is more hierarchy in Ada library units than there is VHDL libraries most particularly subprograms are library units (analogous to design units).

  • Flat library creates serious limitations
    • Project become larger requiring improved namespace management
    • Difficulty ensuring thirdparty libraries integrate together

VHDL libraries have exactly two levels of hierarchy, primary and secondary design units. Further you can note selected names cannot be used to reference subprograms declared and specified in secondary design units. This was specifically banned in VHDL93. Primary units declare, secondary units specify. One level of indirection isn't a hat hook for justifying hierarchy in VHDL because Ada has more. Note Ada has more object class sensitivity than VHDL as well, which is limited to signal sensitivity.

And yes you are trying to add improved name space management.

Ensuring third party libraries integrate together shouldn't be a goal of the language definition. This is an implementation issue.

  • Library structure cannot match directory structure

And library structure cannot match directory structure without adding library recursive hierarchy, which you have not identified in this proposal. Design implementation hierarchy comes about by referencing design units found in a library or subprogram declaration/specification found in a package. No actual nesting of design libraries or primary or secondary units within secondary units is implied in this proposal to date.

  • A simple and logical tweak to the language to bring inline

While restricting hierarchy to name space to date there are issues with complexity. There appears to be a strong desire to use expanded names ("Library hierarchy is defined by . separator characters."). While you could note that by using expanded indentifiers or a different separator character already allowed in an identifier ('_') you can address name space management. Simply by using longer names today. The length of a simple name is implementation defined and there is no general reason to limit it severely.

Without adding actual library hierarchy ("simple and logical tweak") the ability to reference design elements further down the library hierarchy is artificial, there are no declarations in primary units or secondary unit declarative regions enabling visibility further down the hierarchy. The mechanism used to make library simple names would have to be expanded on to define that hierarchy and make it visible. (LRM, 13.2 Design libraries, expanding logical names to embrace selected (expanded) named). This puts specifying the hierarchy squarely in the domain of the implementation ("A given implementation shall provide some mechanism to associate a library logical name with a host-dependent library. Such a mechanism is not defined by the language.").

I'm personally against the promotion of faux hierarchy. There hasn't been any analysis to date on the effects of actually adding real library hierarchy to date. There may be obvious reasons to deny subprograms as design units based on dynamic elaboration. It's likely nested packages can be benign, operating as name space access restrictions. Primary design units already provide the ability to restrict name space access through component declarations in secondary units or through configuration declarations and specifications.

-- DavidKoontz - 2013-08-04

The only use case that has been given for this proposal is hierarchical libraries, so supporting hierarchical name spaces generally seems overkill. For me the question is that of the true requirement; the hierarchical name already proposes a solution.

One problem I have encountered is to provide alternate views of an entity in a library, just as we have alternate "views" of an implementation in the form of different architectures. This issue comes up with changing the abstraction level of a design unit to allow exchanging an entity with signal ports to one with terminal ports. While using a different library for different views may work in many cases with pure VHDL designs, it is restrictive and not user friendly in mixed language contexts.

-- ErnstChristen - 2015-01-21


Add your signature here to indicate your support for the proposal

-- ChrisHiggs - 2011-07-01

-- DanielKho - 2011-07-01

-- MartinThompson - 2011-07-14

-- CharlesGardiner - 2011-08-17

-- MatthiasAlles - 2011-10-27

-- RyanHinton - 2011-11-10

-- DavidBishop - 2011-12-15

-- JonnyDoin - 2013-01-03

-- LarsJensen - 2013-02-18

-- PatrickLehmann - 2014-08-01

-- Brent Hayhoe - 2014-12-17

-- MortenZilmer - 2015-01-21

Topic revision: r20 - 2020-02-17 - 15:34:32 - JimLewis
Copyright © 2008-2020 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback