APS/Vivado Basics/03. Project manager.md

Project Manager

The Project Manager window allows you to manage the project: add and edit project source files, view a brief summary of FPGA resource utilization, browse build logs and messages, and much more.

The primary area of interest is the project sources window, called Design Sources, shown in Fig. 1.

The Design Sources Window

By default, this window is located in the upper-left corner of the Project Manager window. If you accidentally close it, you can restore it via the Windows -> Sources menu.

Figure 1. Project sources window.

The window is divided into three tabs:

1. Hierarchy
2. Libraries
3. Compile Order

In certain situations, an IP Cores tab may also appear, but it is not relevant for this course.

Let us review each tab in order.

The Hierarchy Tab

This tab contains four "folders":

1. Design Sources
2. Constraints
3. Simulation Sources
4. Utility Sources

During this course, we will only work with the first three.

Note that despite the use of the word "folder", these are not file system directories. Project folders are simply a convenient abstraction for managing the project hierarchy.

The Design Sources folder holds the hierarchy of design modules — source files for digital circuits that may eventually be synthesized to an FPGA or an application-specific integrated circuit (ASIC).

The Constraints folder contains constraint files that help implement the project on a specific FPGA (see "FPGA Implementation Steps").

Simulation Sources stores the hierarchy of the verification environment, including modules from the Design Sources folder — that is, all modules (both synthesizable and non-synthesizable) that will be used during simulation.

Note that the Hierarchy tab does not show files. It displays the module hierarchy of the project. A single module can be instantiated multiple times — in that case it will appear multiple times in the hierarchy, even though the file describing that module remains a single file (see Fig. 6).

Adding a File to the Project

To add a new file to the project, click the + icon at the top of the Sources window (or use the keyboard shortcut Alt+A).

The Add Sources dialog will appear. On the first page, select the type of file to add (see Fig. 2):

• Constraint files for synthesizing the design to a specific FPGA (Constraints);
• Design source files (Design Sources);
• Verification environment files (Simulation Sources).

Figure 2. First page of the Add Sources dialog.

Since we want to describe a simple circuit first, make sure Design Sources is selected, then click Next.

The page shown in Fig. 3 will appear, offering three options for adding sources:

1. Add an existing file;
2. Add all files in a specified directory;
3. Create a new file.

Figure 3. Second page of the Add Sources dialog.

Create a new file by clicking the corresponding button. A pop-up window will appear asking you to choose the file type and name (see Fig. 4). In the File Type field, select SystemVerilog (this type will be used throughout the course unless stated otherwise). In the File Name field, enter a name for the new file (in this example, the file name will be max_min). You do not need to specify a file extension — the EDA tool will add it automatically based on the selected file type. When ready, click OK. After all required sources have been added (or created), click Finish in the Add Sources dialog.

Figure 4. New file creation dialog.

If a new file was created, after clicking Finish a window will appear offering to automatically generate a module prototype by specifying port directions and widths through the GUI (see Fig. 5). For this example, decline the offer by clicking Cancel -> Yes.

Figure 5. Module port definition dialog.

After adding the source files, Vivado will automatically begin updating the project hierarchy. You can notice this by the Updating label with a spinning arrow animation shown in Fig. 6.

Figure 6. Project hierarchy update notification.

While this notification is visible, it is not recommended to launch any sub-applications from the Flow Navigator (for example, opening a schematic, running simulation or synthesis, etc.), because the project hierarchy has not yet been built and doing so may result in an error or an action being applied to the wrong module.

Depending on which sub-applications are active in the Flow Navigator at the time the Add Sources window is opened, Vivado will attempt to select the most appropriate option automatically (which may not always match your intent). For example, if you described a module, launched a simulation to verify it, and then decided to describe the next module, the Add Sources window will default to Simulation Sources because the simulation is running in the background at that moment.

Once Vivado finishes updating the hierarchy (and if you declined to specify module ports by clicking Cancel), an arrow will appear next to the Design Sources folder, allowing you to expand it. Inside, you will find a Non-module Files subfolder containing the newly created file. The file is labeled this way because it does not yet contain a module. Once a module is described in it, the subfolder will disappear.

Open the editor by double-clicking max_min.sv and describe the code shown in Listing 1. The code in Listings 1–3 may contain intentional logical errors — these will be identified and corrected in the document "Guide to Finding Functional Errors".

module max_min(
  input  logic [31:0] a,
  input  logic [31:0] b,
  output logic [31:0] max,
  output logic [ 3:0] min
);

  always_comb begin
    if(a > b) begin
      max = a;
      min = b;
    end
    else begin
      max = b;
      min = b;
    end
  end

endmodule

Listing 1. Description of the max_min module.

Do not forget to save the file after writing the module by clicking the floppy disk icon in the editor or pressing Ctrl+S.

Similarly, add files half_divider and vector_abs to Design Sources and describe the modules shown in Listings 2–3 respectively (all listing files are available in the repository under Vivado Basics/vector_abs). On the second page of the Add Sources dialog shown in Fig. 3, you can create multiple new files at once. Make sure you select the correct file type when creating them.

module half_divider(
  input  logic [31:0] numerator,
  output logic [31:0] quotient
);

  assign quotient = numerator << 1'b1;

endmodule

Listing 2. Description of the half_divider module.

module vector_abs(
  input  logic [31:0] x,
  input  logic [31:0] y,
  output logic [31:0] abs
);


  logic [31:0] min;
  logic [31:0] min_half;

  max_min max_min_unit(
    .a(x),
    .b(y),
    .max(max),
    .min(min)
  );

  half_divider div_unit(
    .numerator(min),
    .quotient(min_half)
  );

  assign abs = max + min_half;

endmodule

Listing 3. Description of the vector_abs module.

Add the file tb_vector_abs to Simulation Sources as described in Listing 4.

module tb_vector_abs();

logic [31:0] a;
logic [31:0] b;
logic [31:0] res;

vector_abs dut(
  .x(a),
  .y(b),
  .abs(res)
);
integer err_count = 0;

task check_result(input logic [31:0]a, b, res);
begin : check_result
  reg [31:0] ref_res;
  ref_res = a < b? a/2 + b : a + b/2;
  if (res !== ref_res) begin
    $display("Incorrect res at time %0t:", $time);
    $display("a = %0d, b = %0d", a, b);
    $display("design    res = %0d", res);
    $display("reference res = %0d", ref_res);
    $display("------------------");
    err_count = err_count + 1'b1;
  end
end
endtask

initial begin : test
 integer i;
 $timeformat(-9,0,"ns");
 a = 0; b = 0;
 #5;
 check_result(a,b,res);


 a = 1; b = 1;
 #5;
 check_result(a,b,res);

 a = 3; b = 4;
 #5;
 check_result(a,b,res);


 for(i = 0; i < 100; i=i+1) begin
   a = $random()&32'hff; b = $random()&32'hff;
   #5;
   check_result(a,b,res);
 end

 $display("Test has been finished with %d errors", err_count);
 if(err_count == 0) begin
   $display("SUCCESS!");
 end
 $finish();
end
endmodule

Listing 4. Description of the tb_vector_abs module.

Building the Module Hierarchy

After creating the files listed above and describing the modules from Listings 2–4, the module hierarchy will look as shown in Fig. 7.

Figure 7. Project hierarchy shown in collapsed view.

Clicking the arrow to the left of the vector_abs module will expand the hierarchy (Fig. 8).

Figure 8. Project hierarchy shown in expanded view.

Notice that the vector_abs module is displayed in bold compared to the other modules. This indicates that it is selected as the top-level module. This means it represents the final design being implemented, and other sub-applications in the Flow Navigator — such as RTL ANALYSIS, SYNTHESIS, IMPLEMENTATION, and PROGRAM AND DEBUG — will process this module. If you want to work with a different module (for example, half_divider), you must manually set it as the top-level module. To do so, right-click it and select Set as Top from the drop-down menu (see Fig. 9).

Figure 9. Selecting the top-level module (the middle of the drop-down menu is shown).

Note how the project hierarchy is structured. Modules that are instantiated inside other modules are "nested" within them. In the hierarchy, the instance name is shown first, followed by a colon and the module name. The file where the module is described is shown in parentheses. A module that is not instantiated inside any other module has no instance name (since there is no entity that creates the instance). If a module contains multiple instances of the same module, all of those instances will be shown in the hierarchy — this is why it is important to understand the difference between the module hierarchy and a file tree. Even though a module is described in a single file, multiple instances of it may appear in the project hierarchy.

Hierarchy Errors

If you accidentally placed a file in the wrong folder (for example, added a file intended for Design Sources to Simulation Sources or vice versa), you can move it to the correct folder without deleting and re-adding it. Right-click the file and select Move to Design/Simulation sources (see Fig. 10).

Figure 10. Moving a module to the correct folder.

After adding the tb_vector_abs module, look at the Simulation Sources hierarchy. Notice that all Design Sources modules are duplicated in Simulation Sources. This is another distinction from a file tree. Physically, each module exists in only one file; what is shown here is the module hierarchy.

You will also notice that the top-level module in Simulation Sources is different. The top-level module in Simulation Sources determines which module will be used during simulation (typically a testbench that instantiates the module under test). The top-level modules in Design Sources and Simulation Sources are independent — you do not need to set the module being tested as the top-level in Design Sources in order to verify it using a testbench in Simulation Sources.

Let us change the module name vector_abs used when instantiating the DUT object in tb_vector_abs (for example, to vector). The resulting module hierarchy is shown in Fig. 11.

Figure 11. Project hierarchy with a missing module.

The hierarchy was updated, but since there is no module named vector in the project, this is reflected accordingly. Since vector_abs is no longer part of tb_vector_abs, it is no longer a nested module and appears alongside it in Simulation Sources (the Design Sources hierarchy remains unchanged, as only the tb_vector_abs module located in Simulation Sources was modified).

The Libraries Tab

This tab contains the project files grouped by library. This tab will not be used during this course.

The Compile Order Tab

Vivado normally determines the compilation order from the project hierarchy. However, in some situations it may determine the order incorrectly. This tab allows you to correct the compilation order (most likely you will need this tab to specify the compilation order for SystemVerilog packages).

Additional Resources

More detailed information about the Sources window can be found in the Vivado user guide: "Vivado Design Suite User Guide: Using the Vivado IDE (UG893)" (section "Using the Sources Window").