We have detected your current browser version is not the latest one. Xilinx.com uses the latest web technologies to bring you the best online experience possible. Please upgrade to a Xilinx.com supported browser:Chrome, Firefox, Internet Explorer 11, Safari. Thank you!

Showing results for 
Search instead for 
Did you mean: 

Using the "work" library in VHDL

Xilinx Employee
Xilinx Employee
2 0 689

A powerful feature of VHDL is the use of libraries to organize different sections of RTL.  By using libraries, different designers can work on their own sections of the project without having to worry about naming conflicts with other designers. This is accomplished either by manually specifying which library to use during the instantiation, or by using a configuration statement.

For example, an entity called "bottom" has been created and compiled in a  library called "my_lib1". 

A top level that is compiled into any library can easily reference bottom by using direct entity instantiation:

u0 : entity my_lib1.bottom port map (in1 => in1, out1 => out1);

By using the coding style above, there is no question about which version of bottom is wanted.  The version in the library "my_lib1" is the correct one.

One common misconception is about when a library called "work" is used.  Many designers will use work as a library assuming that like other libraries, it is a physical library.  However, this is not the case. The library called "work" has a special usage in VHDL. 

It is not a physical library, it really means "current library".

When a file is compiled into a specific library and then told to get logic from "work", it does not look in a physical library called work, it looks in the library that the instantiating file is compiled into.  This can be shown with a couple of examples.

Example #1

In this example, there are three files, top.vhd, bottom1.vhd and bottom2.vhd.  Top.vhd is the top level in the design and it instantiates an entity called "bottom".  Both of the two bottom files have an entity called "bottom".  In bottom1.vhd, there is an output that is driven by an input through an inverter.  In bottom2.vhd, the output is driven directly by the input.

image.pngtop.vhd (my_lib1)image.pngbottom1.vhd (my_lib1)image.pngbottom2.vhd (my_lib2)

The top level is compiled into a library called my_lib1, bottom1.vhd is also in my_lib1, and bottom2.vhd is in a library called my_lib2. 

In the top level, the instantiation looks similar to the following:

u0 : entity work.bottom port map (in1=> in1, out1 => out1);

Looking at the elaborated view, the schematic looks like the following example:


image.pngThis is what we are expecting.  More importantly, when simulation is run with the same setup, the waveform looks like the following example:



Next, if the top.vhd file's library is switched from my_lib1 to my_lib2, the elaborated view changes as follows:


And the waveform in simulation also changes:



This is exactly what is expected.  Because the top.vhd file is in my_lib2 and uses "work" in the entity instantiation, it will grab bottom from my_lib2.

Example #2

This example will show the dangers of assuming that work is a physical library.  This is a test similar to Example #1.  In this case, top.vhd and bottom1.vhd will be compiled into the library "my_lib1", and bottom2.vhd will be compiled into a library called "work". 


image.pngtop.vhd (my_lib1)image.pngbottom1.vhd (my_lib1)image.pngbottom2.vhd (work)


As in the previous example, the top level instantiates bottom as follows:

u0: entity work.bottom port map (in1 => in1, out1 => out1);

The elaborated view for this design looks like the following example:


And the simulation looks as follows:


So even though bottom2.vhd was compiled into a physical library called "work" and the top level was instantiating bottom from the library "work", the tool still uses the behavior from bottom1.vhd that was compiled into the same library as top.vhd.

Vivado default libraries:

By default, when entering VHDL files into a Vivado project, the tool will put those files into a library called "xil_defaultlib".  The reason for this is to allow users who are only using one library to easily port older projects into VHDL, while also helping users who have more compilated structures to correctly set up their projects in Vivado.


Care should be taken when choosing library names for VHDL files.  While a library called work is a common library name for many projects, the tool will handle it a little differently than other library names.  If a top level file is compiled into a different library and work is referenced, it will not get the behavior from a physical library called work.  This can lead to confusing behavior if it is not expected.

My recommendation is to never use the library "work".  Instead, always specify which library you want to use when you instantiate lower levels. 

This requires a little more effort, but it will always give you the behavior that you want.