How does "include" work in Verilog?

Question

I've got a problem understanding how include works. My teacher told me that include isn't meant to include modules but constant values.

He said that using the same include module in many modules will make errors because the module with the same name is on 3 other modules (3 different files .SV).

I don't get it. I used includes on testbench, but I should do it. Why?

I don't understand the statement that the same name of the included module is in 3 files.

Update :

Usually I use include in testbench to add other modules for example include "Not_module.sv". But I was told to not do it. I don't know why.

Also the argument to not use include for modules. For example let's say I have a module "not_module.sv" and two other modules "ALU1.sv" and "ALU2.sv"

I need "not_module.sv" in both ALU modules. So I added include in ALU 1 and ALU 2. My teacher said that the synthesis or simulation will not know which include module to compile or something. I don't understand it. Let's say ALU1 uses the not_module to substract something and ALU2 uses not_module to add something. So why compiling ALU1 and ALU2 will complicate it when there is include "not_module.sv"?

Answer 1

'include works as if this line was removed and contents of the included file were inserted exactly were the directive was. This means that if a file with a module is included in more than one place, this design would be interpreted more than once.

Answer 2

I agree with your teacher in saying that is not a good practice to use `include to compile the source description of a module. But, either your teacher is incorrect about the reasons behind not using `include, or you are misunderstanding what your teacher is trying to say. Understanding the compilation steps of your tool, as well as how compilation units and namespaces work in SystemVerilog will certainly help.

Suppose you have the file: file1.sv

`include "i1"
`include "i2"

And the command line (I'm using Modelsim/Questa here, but this applies to most other tools)

vlog file1.sv

The file1.sv is a stream of text that includes two other files i1 and i2.

File i1 could contain

module top;
initial 

and file i2 could contain

$display("hello from top");
endmodule

It the same as if we concatenated the two include files into another called file2.sv and executed the command line

vlog file2.sv

The compiler only knows the source text will be interpreted as SystemVerilog because of the *.sv file extension. File extensions of included files do not matter because you can't change languages via include files. Note there is no required correspondence between the number of files that make up a module, and the number of modules that are in a file. The compiler is just looking at a stream of text.

Every command line is a separate compilation unit (and SystemVerilog allows for every file on the command line to be a separate compilation unit). All of the compiler directives like `define `include `ifdef are isolated to each compilation unit. That means a `define PI 3.14 defined in one compilation unit is undefined in another compilation unit unless there is another `define PI 3.14 in another compilation. That is the reason you see includes of the same definition files in multiple files. Modules exist in a different namespace from compilation units, they are global. (at least global to a tool working library). You only need to compile it once. If you compile it multiple times, it overwrites the previous version stored in the library. The can be further complicated by the fact that it's possible for a tool to group compiled modules into multiple libraries. If you were compile ALU1.sv into one library and ALU2.sv into another library, and both files included not_module.sv, then you wind up with two copies of the same module definition in two different libraries. The same problem exists if you were to synthesize ALU1 separately from ALU2.

Answer 3

The purpose of the include compiler directive is to share common code in different Verilog source code files, typically inside different modules.

A very common usage is to share constants between different modules. For example, the included file can contain a list of parameters such as:

File constants.v:

parameter DATA_WIDTH = 16;
parameter ADDR_WIDTH = 4;

This file can be included into multiple other files.

File1 (design.v):

module design (datain, addr, dataout);
    `include "constants.v"
    input [DATA_WIDTH-1:0] datain;
    input [ADDR_WIDTH-1:0] addr;
    input [DATA_WIDTH-1:0] dataout;
    //...
enmodule

File2 (tb.v):

module tb;
    `include "constants.v"
    reg  [DATA_WIDTH-1:0] datain;
    reg  [ADDR_WIDTH-1:0] addr;
    wire [DATA_WIDTH-1:0] dataout;
    design dut (datain, addr, dataout);
enmodule

The benefit to using include is to allow all your code to be easily scalable to similar designs that have different specifications. For example, if your design represents a memory controller, the same design and testbench files can represent a memory with an 8-bit data bus or a 16-bit data bus; all you need to do is change the common constants.v file.

So, yes, you can use include to share code between design and testbench, as you have been doing.

---

As I said, the above example is a very common usage of include. However, you can get as creative as you want and include any type of legal Verilog code (not just constants) into any other Verilog file. The restriction is that the resultant code must compile without syntax errors.

It is very common to include code that resides inside modules, but there is never any need to use include to include an entire module within another file. The point your teacher is trying to make is that it is illegal to compile the same module more than once when you run a simulation (or synthesis, etc.).