New Sigasi projects are an experimental feature and should be explicitly enabled by the sigasi.project.enableSigasiProjectSupport setting.

Project

Any directory with a valid project description file (project.sigasi) is considered to be a Sigasi project. Sigasi project description is a JSONC (JSON with comments) file. At the top level, it’s a JSON object with the following fields:

Example:

{
    "name": "UVM",
    "version": "2020-3.1",
    "targets": {
        // ...
    }
}

name

A project can be given a logical name that is used to identify it. If the name field is not specified, the name of the directory containing this project.sigasi file is used as the project name.

version

You may want to work with multiple versions of the same design or library. In this case, you can use the version field to differentiate between them. The version of the project can be any string value. No interpretation of the version string is made, e.g., 1.2, 2020-3.1, and latest are all valid versions. If a version is not specified, default is used as a value. The project’s version can be used when specifying a project target dependencies.

targets

A project target defines how to compile project HDL source files. A project should define at least one target. You can define multiple targets as well. In this case, a target can correspond to a specific part or configuration of your project. The sources of each target are compiled and analyzed independently, unless dependencies are explicitly defined. If necessary, same sources can be safely compiled into multiple targets.

Targets are defined in the targets section. Each target consists of a name and a definition. A target name is an arbitrary string that is used to identify it.

There are two ways to define a target:

• Scripted target – allows re-using existing compilation scripts
• Manual target – a declarative way to map project HDL files to libraries

Example:

{
    "targets": {
        "synthesis": { /* synthesis target definition */ },
        "simulation": { /* simulation target definition */ },
    }
}

Scripted Target

You can use supported compiler commands (or scripts that invoke these commands) to define a target. SVH executes specified commands in a target shell, intercepts, records, and analyzes compiler invocations to extract information on what files should be compiled in this target and how it should be done. A scripted target definition can have the following fields:

Example:

{
    "targets": {
        "UVM": {
            "environment": {
                "UVM_HOME": "${SIGASI_PROJECT_DIRECTORY}"
            },
            "command": "xrun -work UVM -incdir $UVM_HOME/src $UVM_HOME/src/uvm.sv"
        }
    }
}

Shortcuts:

Simple scripted target definitions can be specified in a shorter way, e.g.:

command

One or multiple compilation commands. If multiple commands are specified, they are executed in their own shells. You can use any valid shell command or script, or even use your build system command line interface that invokes one of the supported compiler commands.

Specified commands should run full compilation. SVH considers files that were compiled during the last run to be the only project files. If commands perform an incremental build, SVH will see only part of the design.

SVH executes compilation commands as is, and thus don’t have an understanding of what build files contribute to a project structure in case of complex build scripts. To ensure the project structure is up-to-date, SVH detects changes in project directories and re-runs target commands. If compilation commands create or change files in one of the project directories, it may result in a refresh loop.

While SVH tries to avoid them, if you experience a refresh loop, you may want to update your build scripts not to make filesystem changes or disable the sigasi.project.enableAutomaticTargetRefresh setting.

Example:

{
    "targets": {
        "OSVVM": { "command": "vsim -c -do \"source Scripts/StartUp.tcl; build ../OsvvmLibraries\"" },
        "UVVM": { "command": ["mkdir -p vsim", "./compile_all.sh vsim"] }
    }
}

environment

In addition to system environment variables, SVH makes the following environment variables available in the target shell:

If you need more environment variables for your commands or scripts, or you want to override their value, you can do this in the environment section. Values can use other environment variables (supported formats: $ENV_VAR, ${ENV_VAR}, ${ENV_VAR:default_value})

Example:

{
    "targets": {
        "UVM": {
            "environment": {
                "UVM_VERSION": "1.2",
                "UVM_HOME": "${VCS_HOME}/etc/uvm-${UVM_VERSION}",
                "UVM_SRC": "${UVM_HOME}/src"
            }
            // ...
        }
    }
}

ignoreReturnCode

When you use existing compilation scripts, they may fail because SVH intercepts compiler command invocations. If these invocations are supposed to produce artifacts that are required by follow-up commands that are not intercepted by SVH, these commands may fail.

In such cases, you may set ignoreReturnCode to true in the target definition to ignore such failures. It’s recommended to adapt such scripts for SVH, so they don’t fail during normal operation. You can look at environment variables, to check if your script is executed by SVH.

Target Shell

Commands are executed in one of the following shells:

• bash -c <command> on Linux
• cmd.exe /c <command> on Windows

A different shell to use can be configured by defining SIGASI_TARGET_SHELL environment variable. The value should contain a command prefix, e.g: powershell -command, or /usr/bin/zsh -c. Target commands will be appended to the specified prefix before execution.

A directory with supported compiler executable stubs is prepended to shell’s PATH, so no actual compiler invocations are performed by Sigasi. All other commands are executed as is. Additional environment variables are also set before executing commands.

Manual Target

If you don’t have compilation scripts, or would like to use a declarative way to define target sources, you can use the following fields in a target definition:

Example:

{
    "targets": {
        "UVM": {
            "libraryMapping": {
                "src/uvm.sv": "UVM"
            },
            "verilogPreprocessor": {
                "includeDirectories": ["src"]
            }
        }
    }
}

directory

A directory that should contain all HDL sources of this target. If the directory field is not specified, a project directory is considered to be a target sources directory. All other paths specified in this target definition are relative to this directory.

It’s recommended to use project directory (default behavior) or specify a path relative to the project directory. If you need to use a directory that is located somewhere else, you can use environment variables in the directory field value to make it portable. Supported formats: $ENV_VAR, ${ENV_VAR}, ${ENV_VAR:default_value}. Using absolute paths is not recommended, as it makes it harder to use such project files on different systems.

Example:

{
    "targets": {
        "UVM (local)": { "directory": "src", /* ... */ },
        "UVM (other)": { "directory": "$UVM_HOME/src", /* ... */ }
    }
}

libraryMapping

In order for SVH to compile HDL sources, they have to be mapped to a library. This can be done in libraryMapping section. Each key is a path inside the target sources directory. A value is a logical name of a library this path should be mapped to, or a list of library names. Note that the order of specified paths is not relevant, instead, mappings for longer paths have higher priority. You can map individual files, or whole directories. If you map a directory, each HDL file in this directory and in all nested directories will be mapped to the specified library, unless the libraryMapping section contains different mappings for nested directories or files.

You can unmap an HDL file or directory by specifying an empty library names list as a value. In this case, specified file or files in specified directory will not be compiled.

Example:

{
    "targets": {
        "UVM": {
            "libraryMapping": {
                "": [],             // don't map any source file in project directory
                "src/uvm.sv": "UVM" // other than this one
            }
        }
    }
}

ignore

Target sources directory can contain files generated by your toolchains. If there are a lot of such files, it may negatively affect SVH performance. If that’s the case, or you want to see and use only relevant source files, you can specify what files in the sources directory should be ignored by SVH.

One or multiple pattens can be specified. Each pattern follows .gitignore  format.

Example:

{
    "targets": {
        "rtl": {
            "ignore": [
                "*.log",   // Ignore all files that have .log extension in target sources directory
                "**/tmp/*" // Ignore all files in all nested "tmp" directories
            ], 
            // ...
        }
    }
}

languageMapping

In this section, you can specify how files with different extensions should be compiled.

Example:

{
    "targets": {
        "rtl": {
            // ...
            "languageMapping": {
                "vhdlVersion": "vhdl-2008",
                "systemverilogSuffix": [".sv", ".sva"],
            }
        }
    }
}

vhdlSuffix

Specify the list of all VHDL filename suffixes. Files with names that end with specified suffixes (or extensions) will be compiled as VHDL. If the vhdlSuffix field is not specified, files with .vhd and .vhdl extensions will be compiled as VHDL.

verilogSuffix

Specify the list of all Verilog filename suffixes. Files with names that end with specified suffixes (or extensions) will be compiled as Verilog. If the verilogSuffix field is not specified, files with .v extension will be compiled as Verilog.

systemverilogSuffix

Specify the list of all SystemVerilog filename suffixes. Files with names that end with specified suffixes (or extensions) will be compiled as SystemVerilog. If the systemverilogSuffix field is not specified, files with .sv extension will be compiled as SystemVerilog.

vhdlVersion

Specify what VHDL version should be used to compile VHDL sources. Supported versions: vhdl-1993, vhdl-2002, vhdl-2008, and vhdl-2019. If the vhdlVersion field is not specified, the default (vhdl-2019) version is used.

verilogVersion

Specify what Verilog or SystemVerilog version should be used to compile Verilog sources. Supported versions: verilog-2005 and systemverilog-2012. If the verilogVersion field is not specified, the default (verilog-2005) version is used.

systemverilogVersion

Specify what SystemVerilog version should be used to compile SystemVerilog sources. Currently, only one version is supported: systemverilog-2012.

override

If some files should be compiled with a different VHDL or Verilog version, you can specify this in the override section.

Each key is a path inside the target sources directory. If the path denotes a file (with any extension), you can specify VHDL or Verilog version to compile this file with as a value directly. If the path denotes a directory, you can specify versions to use for VHDL, Verilog, or SystemVerilog files in this directory and in all nested directories, unless the override section contains different versions for nested directories or files. You can do this by defining following fields in a value object:

Example:

{
    "targets": {
        "rtl": {
            // ...
            "languageMapping": {
                "vhdlVersion": "vhdl-2008",             // By default use VHDL-2008 to compile all VHDL files
                "override": {
                    "otherlib/src": {                   // Files in "otherlib/src" directory should be compiled differently
                        "vhdl": "vhdl-2019",            // VHDL files should be compiled as VHDL-2019
                        "verilog": "systemverilog-2012" // Verilog (.v) files should be compiled as SystemVerilog files
                    },
                    "otherlib/src/core/legacy.vhdp": "vhdl-1993", // This file is an exception, and should be compiled as VHDL-1993
                }
            }
        }
    }
}

vhdl

Version to use for VHDL files in the target sources directory specified in the override section. If not specified, a default VHDL version, version specified by vhdlVersion field, or version specified for the parent directory in the override section will be used. If necessary, you can specify non-default filename suffixes of your VHDL files in the vhdlSuffix field.

verilog

Version to use for Verilog files in the target sources directory specified in the override section. If not specified, a default VHDL version, version specified by verilogVersion field, or version specified for the parent directory in the override section will be used. If necessary, you can specify non-default filename suffixes of Verilog files in the verilogSuffix field.

systemverilog

Version to use for SystemVerilog files in the target sources directory specified in the override section. If not specified, a default VHDL version, version specified by systemverilogVersion field, or version specified for the parent directory in the override section will be used. If necessary, you can specify non-default filename suffixes of SystemVerilog files in the systemverilogSuffix field.

verilogPreprocessor

If necessary, you can specify Verilog include directories or initial defines for all Verilog source files in the verilogPreprocessor section. You can also configure SVH to compile each Verilog file in its own compilation unit. Following fields are available:

Example:

{
    "targets": {
        "rtl": {
            // ...
            "verilogPreprocessor": {
                "multiFileCompilationUnitScope": false
            }
        }
    }
}

includeDirectories

By default, files specified in `include "<filename>" statements are searched only in the targets sources directory. If you would like to use paths relative to other directories in include statements, you can add these directories in includeDirectories field value.

Example:

{
    "targets": {
        "rtl": {
            // ...
            "verilogPreprocessor": {
                "includeDirectories": [
                    "src",
                    "otherlib/include"
                ]
            }
        }
    }
}

define

Whenever you need to set initial defines for your design, you can do this in the define section. Each key is a name of the macro to define. A value is its body. Value can be an empty string or null if macro should be defined without a body

Example:

{
    "targets": {
        "rtl": {
            // ...
            "verilogPreprocessor": {
                "define": {
                    "CPU": "cpu", // Equivalent to `define CPU cpu
                    "VCS": ""     // Equivalent to `define VCS
                }
            }
        }
    }
}

multiFileCompilationUnitScope

By default, all Verilog files are compiled in a single compilation unit, setting multiFileCompilationUnitScope to false will configure SVH to compile each Verilog file in its own compilation unit.

vhdlConditionalAnalysis

Similar to verilog defines, in the vhdlConditionalAnalysis section you can define string identifiers and values which are visible to VHDL-2019 conditional analysis directives.

Example:

{
    "targets": {
        "rtl": {
            // ...
            "vhdlConditionalAnalysis": {
                "TOOL_TYPE": "SIMULATION",
                "DEBUG_LEVEL": "2"
            }
        }
    }
}

Dependencies

Defining a dependency on another target makes HDL definitions from that target sources available in current target sources, as well as in sources of all targets that would depend on this target. You can define dependency on:

• Another target of the same project (cannot be added for the whole project, only for individual targets)
• One or multiple targets of another project
• Library from the Library Database

Each dependency is either a string with the name of another target of this project, or an object with another project name as a key, and an object with the following fields as a value:

Shortcuts:

When you want to specify only version or target, a shorter version of a dependency declaration is available:

Example:

{
    "dependencies": [ // Dependencies for all targets of this project:
        // Dependency on all targets of another project with the name "common_cells" and version "1.0"
        { "common_cells": "1.0" },
        // Dependency on target with the name "rtl" of another project with the name "apb_uart"
        { "apb_uart": ["rtl"] }
    ],
    "targets": {
        "ip1": { /* ... */ },
        "rtl": {
            // ...
            "dependencies": [ // Dependencies only for this target:
                // Dependency on another target of this project with the name "ip1"
                "ip1",
                // Dependency on the UVM 1.2 library from the Library Database
                { "UVM": "1.2" },
                // Dependency on highest Quartus "altera" and "lpm" libraries from the Library Database
                { "Quartus": [ "altera", "lpm" ] }
                // Dependency on Vivado 2023.2 "unisim" library from the Library Database
                { "Vivado": { "version": "2023.2", "targets": [ "unisim" ] } }
            ]
        }
    }
}

When you specify a dependency on another project or library from the Library Database, it is searched in:

• VS Code workspace folders.
• Paths specified in the sigasi.dependenciesSearchPaths setting.
  • SVH searches for projects recursively in specified directories.
  • Dependency search path can also point to a Library database, allowing using multiple Library Databases if necessary.
• Path To Library Database specified in the sigasi.pathToLibraryDatabase setting.
• Built-in Library Database (is shipped with SVH, and contains following UVM library versions: 1.1d, 1.2, 2017-1.1, 2020-3.1).

These locations are searched in order, and the first project or Library Database library that satisfies dependency requirements (name and version) is used.

version

If dependency version is not specified, the highest version found is used. Note that currently SVH does no interpretation of version strings, so:

• highest version is determined by simple comparison of version strings
• currently there’s no way to specify more complex version requirements (e.g. defining version ranges), only direct match.

Because of SVH limitations, only one version of the project or library can be present in a target dependencies tree. If the dependencies tree contains multiple versions of the same project or library, the last specified version (in other words, a version specified closer to the current target in a dependencies tree) is used.

targets

Specify a list of targets of referenced project that should be available in current target. If no targets are specified, all targets from the referenced project become available. If an empty list is specified, no targets (other than targets already specified by other dependencies) are added.

Example:

{
    "targets": {
        "common": {
            // ...
            "dependencies": [ { "Vivado": { "version": "2021.1", "targets": [ "unisim" ] } } ]
        },
        "rtl": {
            // ...
            "dependencies": [
                "common",
                // Incorrect way to override version (it overrides version, but also adds all Vivado libraries):
                { "Vivado": "2023.2" },
                // Correct way to override version (it overrides version, and does not add any new libraries):
                { "Vivado": { "version": "2023.2", "targets": [] } }
            ]
        }
    }
}