include file organization

[alb]

Hi there,

I'm pretty new to verilog, even though I've been writing C since some time and
the language is pretty easy to pick up. I have an issue though with the
'include' directive and the way to organize the included dirs.

We are using Cadence at work and it looks like the -incdir is the way to include
directories to look for files which are included in other files.

Assuming the following dir structure:


../sandbox/project/components/
├── module1
│   ├── include
│   └── src
└── module2
├── include
└── src

Now if in my module1 I want to include something, I can directly specify an
incdir that points to module1/include and then in the src files I can simply
write:

`include "file_to_be_included.vh"

The same can be done with module2 but if for some reason the file_to_be_included
have a file with the same name I cannot do it anymore since the tool wouldn't
know which one to pick. Therefore my name space is too broad.

OTOH if I pick an upper level directory to be included (e.x. components) then I
would need to write:

`include "module1/include/file_to_be_included.vh"

This has the benefit to allow modules to have same filenames but I have to know
the incdir directive in order to fully know where is my file and this breaks
portability as well as encapsulation (the module needs an external directive
that is project related instead of module related).

On top of that I find superconfusing that the relative path is relative to the
incdir instead of the source file location. It makes understanding and
navigating the code quite awful.

I said to myself that there must be a better way to organize files in the
project in order to handle this.

Any ideas/suggestion/comment is greatly appreciated.

Al

--
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing on usenet and in e-mail?

 

[GaborSzakacs]

alb wrote:

Hi there,

I'm pretty new to verilog, even though I've been writing C since some time and
the language is pretty easy to pick up. I have an issue though with the
'include' directive and the way to organize the included dirs.

We are using Cadence at work and it looks like the -incdir is the way to include
directories to look for files which are included in other files.

Assuming the following dir structure:


../sandbox/project/components/
├── module1
│ ├── include
│ └── src
└── module2
├── include
└── src

Now if in my module1 I want to include something, I can directly specify an
incdir that points to module1/include and then in the src files I can simply
write:

`include "file_to_be_included.vh"

The same can be done with module2 but if for some reason the file_to_be_included
have a file with the same name I cannot do it anymore since the tool wouldn't
know which one to pick. Therefore my name space is too broad.

OTOH if I pick an upper level directory to be included (e.x. components) then I
would need to write:

`include "module1/include/file_to_be_included.vh"

This has the benefit to allow modules to have same filenames but I have to know
the incdir directive in order to fully know where is my file and this breaks
portability as well as encapsulation (the module needs an external directive
that is project related instead of module related).

On top of that I find superconfusing that the relative path is relative to the
incdir instead of the source file location. It makes understanding and
navigating the code quite awful.

I said to myself that there must be a better way to organize files in the
project in order to handle this.

Any ideas/suggestion/comment is greatly appreciated.

Al

Welcome to the stone-age world of EDA tools. Everything you've learned
about file organization is going to be Cadence-related. Every other
tool vendor will use their own method of finding include files. Some
tools have the concept of a project root directory, and they allow
relative paths starting from the project root. In general, handling
include files in Verilog is a mess. You're only adding to the mess if
you re-use file names when the file contents are different. I generally
try to stay away from include files altogether, which is easier if you
don't have a lot of macros (`define) in your code. A common approach to
a project with tons of macros is to put them all in a single include
file and include that from every source that needs any of the macros.
Remember that macros are global in scope, but because they are a pre-
processor function, that scope means anything compiled after the macro.
This means that you can run into problems with order of compilation,
especially if some macros are redefined. Your best bet at this point
is to ask around at your work to see what is the preferred way to handle
macros and include files, as well as all other project file organization.
Keeping a consistant file structure among projects is important especially
in a large engineering group, since it saves time when you need to
pore through a project created by someone else in the group.

--
Gabor

 

[alb]

GaborSzakacs <gabor@alacron.com> wrote:

Welcome to the stone-age world of EDA tools. Everything you've learned
about file organization is going to be Cadence-related. Every other
tool vendor will use their own method of finding include files. Some
tools have the concept of a project root directory, and they allow
relative paths starting from the project root. In general, handling
include files in Verilog is a mess.

This is actually what I also thought, but even if I do not like to feel the
vendor's strings on my flow, I prefer using it rather than fight against it. The
problem stays though, the freedom of file inclusion is as messy as in C.

When I was mainly working with C, we used to eventually dump all the .h files in
the same /include dir and everyone was happy. I guess maybe this is what I also
should do here. We have mainly digital part in verilog, the analog models in
SystemVerilog and/or Verilog-A(MS) and the testbench which is typically in SV
driving VAMS for the physical connection to the DUT. The digital and the analog
come with their own set of includes on top of the one from the bench. This is
when things become shaky and scope or namespace become uncertain.

You're only adding to the mess if you re-use file names when the file contents
are different.

I agree and certainly it is unlikely that filenames of different parts match,
but the difficulty to trace down in which directory is the included file still
stays. Should I wander in all the -incdir?

I generally try to stay away from include files altogether, which is easier if
you don't have a lot of macros (`define) in your code.

Unfortunately not the case here, we have an overwhelming set of MACROs, `ifdef
directives, and the configuration space is filled up by a set of scripts whose
region of action is not perfectly clear, exposing to overlap in functionality
and therefore the chance to have an unwanted configuration ending up in the
simulation.

A common approach to a project with tons of macros is to put them all in a
single include file and include that from every source that needs any of the
macros. Remember that macros are global in scope, but because they are a pre-
processor function, that scope means anything compiled after the macro.

a very well known 'feat' from my previous life coding C! Except for very few
exception most of the time I didn't really like the use of macros, there's no
type check and very simple typing mistakes can pass unnoticed.

This means that you can run into problems with order of compilation,
especially if some macros are redefined.

That is another 'feat' I like a lot. Considering the amount of lines of code we
deal with (in the hundreds of thousands), the chance that the same macro is
redefined in two different places is not so dim.

Your best bet at this point is to ask around at your work to see what is the
preferred way to handle macros and include files, as well as all other project
file organization.

I'd definitely do that, I believe that we need to find a common environment
where project navigation can be simpler and shared amongst us.

Keeping a consistant file structure among projects is important especially in
a large engineering group, since it saves time when you need to pore through a
project created by someone else in the group.

That is yet another subject source of frustration and pain! I'll reserve that
for another thread ;-).

Al

--
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing on usenet and in e-mail?