# 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.

![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_01.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_01.png)

_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"](../Introduction/Implementation%20steps.md#implementation)).

`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`).

![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_02.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_02.png)

_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.

![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_03.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_03.png)

_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.

![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_04.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_04.png)

_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`.

![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_05.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_05.png)

_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_.

![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_06.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_06.png)

_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](./05.%20Bug%20hunting.md)".

```Verilog
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](./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.

```Verilog
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._

```Verilog
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_.

```Verilog
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_.

![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_07.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_07.png)

_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_).

![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_08.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_08.png)

_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_).

![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_09.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_09.png)

_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_).

![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_10.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_10.png)

_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_.

![../.pic/Vivado%20Basics/03.%20Project%20manager/fig_11.png](../.pic/Vivado%20Basics/03.%20Project%20manager/fig_11.png)

_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)"](https://docs.xilinx.com/r/en-US/ug893-vivado-ide) (section ["Using the Sources Window"](https://docs.xilinx.com/r/en-US/ug893-vivado-ide/Using-the-Sources-Window)).