Sigasi Visual HDL (SVH) offers a new and sophisticated workflow to improve re-usability of design build configurations. It is built on top of a new Sigasi project format that replaces Eclipse Compatible Projects currently used by SVH.

Sigasi Projects

Sigasi project consists of one or more build targets. Each target describes how to build an artifact of your project. An artifact could be a library, a synthesizable component, a test-bench, etc. There are two types of project build targets, each provides a different way of specifying sources:

1. Scripted targets: allow re-using existing compilation scripts.
2. Manual targets: provide a declarative way to specify the sources that are part of the target and the libraries into which the sources are compiled.

You can also reuse libraries or components that are defined by targets by adding dependencies between them.

Scripted Targets

Many EDA projects have build scripts that start simulations. These build scripts already contain a detailed description of the designs your team is working on. Using Sigasi project scripted targets, you can avoid duplicating the information already present in your build scripts: SVH will extract all relevant information from the build scripts itself.

Manual Targets

Manual targets can be used when you want Sigasi to be in the driver seat and be the main source of information on how to build a design. They provide control similar to Eclipse Compatible Projects, but allow specifying everything in a single place, and benefit from the dependencies mechanism provided by Sigasi projects.

Dependencies

It’s possible to define dependencies between targets. Defining a dependency on another target makes HDL definitions from that target sources available in current target sources. It’s possible to define dependency on:

• Another target of the same project
• One or multiple targets of another project
• Library from the Library Database

In addition, SVH now comes with a built-in UVM library. So adding UVM support to a Sigasi project is as easy as adding a single dependency to a project.

Refer to Sigasi Project Description File Reference for more details about Sigasi project, targets and dependencies.

New Settings Format

When using Sigasi projects, a new settings format is available. It allows easier sharing of configuration between teams and projects, as well as more fine-grained control by allowing target-specific settings.

Refer to the Sigasi Settings File Reference for more details on this new settings format.

Using Sigasi Projects

Creating a Sigasi Project

You can create a new Sigasi Project by opening the Command Palette (Ctrl+Shift+P) and typing to select Sigasi: Add Experimental Sigasi Project…

The wizard creates a new project.sigasi file, which looks something like this:

{
    "name": "MyProject",
    "targets": {
        // define targets
        "hdl": {
            "libraryMapping": {
                "": "work"
            }
        }
    }
}

This file should be either in the root folder of the project, or inside a .sigasi folder in the root of that project.

Sigasi Project Example

Let’s look at a simple project example that illustrates some of the Sigasi project concepts:

{
    "name": "MyProject",
    "targets": {
        "rtl": {
            "environment": {
                "VARIABLE_A": "value",
                "VARIABLE_B": "${VARIABLE_A}"
            },
            "command": [
                "vcs -f ip/list.f",
                "vcs -f src/list.f"                
            ],
            "ignoreReturnCode": false
        },
        "tb" : {
            "dependencies": [ "rtl", { "UVM": "1.2" } ],
            "libraryMapping": {
                "testbench/src": "testbench"
            },
            "ignore": [ "**/sim/*" ]
        }
    }
}

From top to bottom, the following configuration is deduced from the JSON:

1. A Sigasi project has a name. In the example, the project’s name is MyProject.
2. Two targets are listed to assemble the contents of the project. A target comprises a self-contained set of files that are compiled together. You can give a target a logical name. The first target in the example above is called rtl, the second one is called tb.
   1. The scripted rtl target runs two simulator commands to compile the RTL code of the project. The argument files ip/list.f and src/list.f are maintained as part of the project’s build system and can be reused directly. This target also defines custom environment variables.
   2. The manual tb target instructs to compile all HDL sources in testbench/src directory into a testbench library. At the same time, all files generated by a simulator in sim directories should be ignored. This target also defines a dependency on the rtl target (making all the design units compiled there available for the testbench code), as well as a dependency on the UVM 1.2 library shipped with SVH.

Refer to Sigasi Project Description File Reference for more details about Sigasi project, targets and dependencies.

Projects View

To accommodate new Sigasi project concepts, the Sigasi Projects View represents such projects differently. The structure of the captured project is visualized in two different forms: as a filesystem centric Design perspective and as a logical Targets perspective.

The Design perspective allows navigating the structure of all directories that contribute to the project. The captured information from the build script might refer to files from various locations on disk, configure include paths, or rely on files that are located on shared drives. All the directories are accessible in the Design folder.

The Targets perspective reveals the logical structure of the project. For each defined target, a folder represents the libraries and their associated files. The files are rendered in the order of compilation wherever possible. This view will also reveal if some files are mentioned in the build scripts but are missing on disk.

You can open source file in the Targets perspective from the Code Lens at the top of the file.

Manual Target Configuration

Library Configuration

VHDL libraries are fully supported. For Verilog/SystemVerilog, Sigasi reuses the VHDL library concept (just work in practice) to distinguish between design files that should and shouldn’t be analyzed.

To change library mappings, you can use the right-click menu in the Sigasi Projects View and select Change Library as shown in the image below.

You can right-click on individual files, folders, or a selection containing multiple files and/or folders, as well as the entire project or the Design folder, to change library mappings. If multiple targets are available, a dialog will prompt you to select one.

This step will be skipped if there’s only one target available, such as when right-clicking on items in the Targets perspective. Then, you can either select an existing library or type a new library name.

• If you type a new name, a new library will be created and the selected items will be added to it.
• To use an existing library, simply pick one from the list (for example, work)

If you want to remove files/folders from a target, select Remove from Build. Note that the removed resource(s) will still be visible in the Sigasi Projects View, and you can still add them (Change Library) to the project.

Creating new libraries, adding a file/folder to an existing library, or excluding files/folders from the build will modify your project’s project.sigasi file.

VHDL Version

To change the VHDL version, right-click on a project, folder, or file in the Sigasi Projects View and click Configure > Language Version. If there is more than one target available, you will be prompted to select one.

Then, you can select a VHDL version for your project, folder or file.

How Do Scripted Targets Work?

To capture and record the semantics of the build scripts specified in scripted targets, SVH executes them in a prepared shell environment. There, the simulators or compilers (the tools) are shadowed by so-called stub implementations. These stubs capture the command invocations and their execution context as a compilation log. Subsequently, the captured compilation log is interpreted and converted into a detailed compilation plan that contains all participating files and directories in the order of their appearance. The compilation plan is used to derive the underlying logical structure of the target.

The mechanism is generally agnostic to the chosen build technology, as long as it launches the supported tools as external processes from a regular shell environment by their simple executable name.

Supported Compilers

The list of tools that are natively supported and can be introspected on Linux and Windows can be found here.

It should be noted that the tool stubs do not call the original tool. They do not create any artifacts besides adding information to the compilation log. That is why the project structure can be captured on any machine, even if the simulators or compilers are unavailable. The utilities that are used to run the build scripts are required though, e.g., make, perl, python, or any other command line based build technology that is used. Some compiler options may need environment variables to be interpreted correctly.

Predefined Environment Variables

SVH launches the build in a prepared environment, where the PATH variable is prefixed with a directory that contains the stub executables. In addition, SVH sets additional environment variables. They allow SVH specific augmentation of the build scripts.

Caveats and Troubleshooting

Capturing the project structure works best if the build scripts respect the following rules:

1. The configured commands should not cause side effects. If code generation is necessary for a project to work, it is best if the generation step is either not part of the build or repeated runs of the build do not regenerate from scratch but keep the existing generated files untouched.

2. When your build script is triggered from within SVH, ensure that your build script builds all your artifacts from scratch. Avoid triggering an incremental build. An incremental build will not reveal to SVH all build operations and artifacts. This will result in an incomplete Sigasi project being captured. For example, make --always-make should be used to ensure that subsequent builds still run the entire pipeline.

3. The build might still have accidental side effects. Since SVH attempts to capture targets automatically if some meaningful change on disk is detected, it might go into a build loop. Although this situation will be detected by the tool, the build script should be adjusted to avoid side effects. The automatic refresh of targets can be disabled by the sigasi.project.enableAutomaticTargetRefresh setting:

   

   After disabling automatic refresh, you can refresh targets manually by using Code Lenses in the project.sigasi file.

If you encounter any problems with compilation scripts, you can check a few log files that can help you debug the issue. In a project directory, SVH creates .sigasi/targets/<target name> directory for every scripted target. It contains following files:

• compilation.log – contains all intercepted compiler invocations with arguments, working directory, and environment variable values they were invoked with
• compilation.out – standard output stream (stdout) of compilation process
• compilation.err – standard error stream (stderr) of compilation process
• compilation.plan – structured information about files that are compiled as well as how they are compiled

Code Lenses in the project.sigasi file allow to quickly open some of these files.