How should I arrange files of my digital design project?

So for the first time I am creating a project that has a lot of VHDL files containing packages, entity-architecture and test benches and the design is hierarchical of course.

I have all the package, entity-architecture, test bench files in the same folder. There are also a few files containing code that is only used in test benches like a BFM.

Where can I find guidance on the most effective way to arrange these files.

I think one way is to have seperate folders for package, entity-architecture, and testbench and then have .do scripts one level higher and just run them to start all test benches and compile all files. Any advice?

each company has their own system/folder structure, to my knowledge no one follows any standard on this.

I would recommend that you at least separate implementation from verification. also separate scripts from both.

keep libraries together, and in each library have folders:
doc
sim
src

libraries would be re-useable ip sets.

Having packages in one folder and entities in another is a mess.

a typical project might look like:
/fpga/
/fpga/src/
/fpga/<ip>/src/
/fpga/<ip>/bld/
/fpga/<ip>/bin/
/fpga/<ip>/doc/
/fpga/<ip>/sim/
/fpga/bld/
/fpga/bin/
/fpga/doc/
/fpga/sim/

But developers will have slightly different opinions. In this case, doc = documentation, sim = simulation, bld = constraints and build scripts, bin = any scripts or programs related to this ip.

This is for a pure HW, single fpga structure. for mixed hw/sw and multi-fpga systems, there may be more folders.

Likewise, there are several things that can get left out. For example, leaving out /src or /<ip>/src. There shouldn't be any IP named "sim" or "doc", so there shouldn't be much confusion in leaving out the "src" name.

Similarly, /fpga/src is intended to be the top level design. This could also be in a "top" library instead.

/fpga/<ip>/bld might not be applicable, or the code might be placed in /fpga/bld. This can be based on the build system as well as how the repository is structured. At some companies, each fpga design will be in a self-contained repository. At others, ip will be in repositories and references to a branch/version will be included in the main project repository instead.

having a separate package folder doesn't offer as much benefit, and _pkg.vhd can be used to denote a package. Packages are less needed with VHDL as you can use "entity work.my_instance" to avoid component declarations (either locally or in a package). The only time you need "component" is for things like coregen -- black-boxes. As a result, you really only need packages for 3rd party IP, types, functions, and procedures.


In the end, there is a wide variety of structures and they are often imperfect and influenced by the requirements of the tools used by the company.

this is for personal project that seems to have more code than average and is difficult to connect up with all the entities, anyway thanks for your input

OK, on the same issue, please look at this screenshot from my modelsim. do you think there is a better way to organize these files within the modelsim viewer? how?

Use more libraries rather than compiling everything into the work library. You could have a SPI_lib and flash_control_lib from that code.
Also, I hardly ever use the source browser, and never use the modelsim editor unless im putting some break-points in code for debugging. All code is compiled in our script flow. You just list all the source files in a tcl file, and any other libraries this design relies on, and the scripts compile everything for us.

I recommend not using the gui at all, and maintaining everything in tcl files.

IMO, this is an acceptable amount to put into the work library.

I say this because VHDL libraries are convenient and confusing. Specifically, the main library of "work" is treated specially and in a manner that can be annoying and cause issues with different tools.

And I agree. The source browser is a thing that only exists in your mind if you edit files from modelsim/questa.

OK, I will try to have than one library, perhaps one for testbenches, another for RTL and another for packages and no library named work.
And I wil use tcl scripts to do all the compiling, starting simulation, adding waves, run it, save it with special wlf name and so on

matrixofdynamism said:

OK, I will try to have than one library, perhaps one for testbenches, another for RTL and another for packages and no library named work.
And I wil use tcl scripts to do all the compiling, starting simulation, adding waves, run it, save it with special wlf name and so on

Click to expand...

Separating packages, testbenches and RTL into separate libraries is just confusing and feels very wrong.
Put sepearate designs into separate libraries, so all packages, testbenches and RTL related to the same IP block go in the same library.

Possible considerations:

* Make it easy to save a version of your entire project, in case you want to test widespread changes (example, change of variable names, memory usage, handling of user input, display formats, sequence of subroutines). After testing you may decide you want to discard the changes and revert to the previous version.

* Make it easy to back up your entire project. If any file were to be corrupted, you'll want to substitute a duplicate.

* Do you think you might want to run your project on a different computer? Devise a file/folder scheme that allows easy transfer.

It feels bad to have packages in a different library from their related logic.

Just remember that, within the VHDL files, there is no library called "work". "work" is special as it refers to the library the file was compiled/elaborated for. Sadly, the default library developers use is actually named "work". As a result, there is no way for a file compiled into library = not_work to refer to anything in library = work. Attempting to do so would try to find things in not_work, as references to the "work" library within the file will resolve to "not_work" -- the current library -- instead of the library that has been named "work".

This can be solved by never having a library named "work", or in some cases by compiling the file into two libraries. Some tools don't allow the latter.