Project

Any directory with a valid project description file (project.sigasi or .sigasi/project.sigasi) is considered to be a Modular Sigasi project. Modular 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 has a mandatory, logical name that is used to identify it.

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:

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

Scripted Target

You can use any supported compiler commands (or scripts that invoke these commands) to define a target. Sigasi executes the specified commands with the selected interpreter, and intercepts, records, and analyzes compiler invocations to extract information. It determines which files should be compiled for this target and how that should be done, deriving the exact project structure. A scripted target definition can have the following fields:

Example:

{
    "name": "Scripted Target",
    "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.:

acceptUnsupportedOptions

When Sigasi analyzes compiler invocations from a target compilation commands, it looks only at a limited set of compiler options that can affect project structure. The list of supported options can be found on the Supported Compilers page.

Sigasi reports encountered options that it does not support yet. You can verify that the reported options do not affect how your HDL files are compiled, so Sigasi can safely ignore them. Specifying such options in the acceptUnsupportedOptions field will suppress corresponding “unsupported option” warnings. You can specify options for all compilers or for specific ones. It’s also possible to use wildcards (*, ?) to match multiple options.

Example:

{
    "name": "Unsupported Options",
    "targets": {
        "all-options": { 
            "command": "vcs -f filelist.f",
            "acceptUnsupportedOptions": "*" // Suppress all unsupported option warnings in this target commands
        },
        "multiple-options": { 
            "command": "xrun -f filelist.f -timescale 1ns/1ps -access +rwc",
            "acceptUnsupportedOptions": ["-timescale", "-access"]
        },
        "options-by-compiler": { 
            "command": "make -f myMakeFile",
            "acceptUnsupportedOptions": {
                "qrun": "*",
                "vcom": "-O?", // Suppress vcom optimization options, e.g. -O0, -O1, -O5
                "vlog": ["+permissive", "-svinputport=compat"]
            }
        }
    }
}

autoRefresh

By default, targets are automatically refreshed whenever changes are detected in any of the project’s directories. You can disable this behavior by adding autoRefresh: false to your target configuration.

In most cases, however, it is preferable to modify the command so that it does not cause any side effects. If that is not possible, consider using the ignore field to ignore specific files or folders.

command

One or multiple compilation commands. If multiple commands are specified, they are executed in their own interpreters. You can use any valid shell or TCL command, script, or even your build system command line interface that invokes any of the supported compiler commands. Additionally, commands to Import Third-Party Projects are provided by a bundled Sigasi TCL package.

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

Sigasi executes compilation commands as is and thus doesn’t have an understanding of what build files contribute to a project structure in the case of complex build scripts. To ensure the project structure is up-to-date, Sigasi 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 Sigasi tries to avoid refresh loops, they can still occur in some cases. If you encounter one, you may want to:

1. Adjust your build scripts to not make filesystem changes when executed within Sigasi (check environment variables defined by Sigasi).
2. Use intercept field to make Sigasi intercept and ignore program invocations that make filesystem changes.
3. Use ignore field to make Sigasi ignore changes in specified files.
4. Use autoRefresh field to disable automatic refresh of the target structure regardless of any file changes.

Example:

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

ignore

Commands might generate files that are irrelevant to Sigasi. These files can trigger a target refresh and subsequent command executions, causing a refresh loop where files are repeatedly regenerated or modified. If that’s the case, or if you want to see and use only relevant source files, you can specify what files in the source directory should be ignored by Sigasi.

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

Example:

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

ignoreReturnCode

When you use existing compilation scripts, they may fail because Sigasi intercepts compiler command invocations. If these invocations are supposed to produce artifacts that are required by follow-up commands that are not intercepted by Sigasi, 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 Sigasi so they don’t fail during normal operation. You can check for environment variables to adjust the behavior of compilation scripts when they are executed by Sigasi.

intercept

When refreshing a scripted target structure, Sigasi executes the configured compilation commands and intercepts compiler invocations for further analysis. If your existing scripts perform operations unrelated to generating or compiling HDL sources, they may slow down the refresh process, modify files in ways that prevent a subsequent full compilation, or even trigger a refresh loop. In such cases, you may want to configure Sigasi to intercept and ignore program invocations that perform these unwanted operations.

By default, in addition to compiler invocations, Sigasi also intercepts invocations of touch. You can customize the set of programs to intercept and ignore using the intercept field. All intercepted invocations are recorded in compilation.log as comments.

Example:

{
    "name": "Intercept Programs",
    "targets": {
        "vunit": {
            "command": "make --always-make --keep-going -f scripts/Makefile",
            "intercept": [ "touch", "g++" ] // Intercept and ignore invocations of "touch" and "g++" from Makefile
        }
    }
}

interpreter

Specify the interpreter to use to run the target commands. It is possible to use either shell commands (scripts), or TCL commands to define a target. If the interpreter field is not specified, commands will be executed by a shell.

shell

If a shell is chosen as an interpreter, 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.

tcl

If the tcl interpreter is chosen, commands are executed in a built-in TCL 8.6 shell.

TCL commands are expected to invoke compiler commands via exec. These invocations are intercepted by Sigasi, similar to shell commands. E.g., instead of directly calling vcom or vlog, you need to use corresponding executables (exec vcom {*}$args), or pass them to vsim executable: (exec vsim -do $commands).

A directory with supported compiler executable stubs is prepended to the 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.

In addition to standard TCL libraries, you can use commands to Import Third-Party Projects from a bundled Sigasi package, or Add your own TCL packages or procedures to make them available in target commands.

Example:

{
    "name": "VUnit",
    "targets": {
        "vunit": {
            "interpreter": "tcl",
            "command": "import_vunit -venv $MY_VENV run.py"
        }
    }
}

Note: You can use environment variables in the command. Sigasi will substitute their values before passing the command to the TCL interpreter.

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:

{
    "name": "Manual Target",
    "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 source directory. All other paths specified in this target definition are relative to this directory.

It’s recommended to use the 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}, and ${ENV_VAR:default_value}. You can also use paths relative to the home directory (e.g. ~/some/path). Using absolute paths is not recommended, as it makes it harder to use such project files on different systems.

Example:

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

libraryMapping

In order for Sigasi 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:

{
    "name": "Library Mapping",
    "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 Sigasi performance. If that’s the case, or if you want to see and use only relevant source files, you can specify what files in the source directory should be ignored by Sigasi.

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

Example:

{
    "name": "Ignore Files",
    "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:

{
    "name": "Language Mapping",
    "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:

{
    "name": "Language Mapping Override",
    "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 Sigasi to compile each Verilog file in its own compilation unit. Following fields are available:

Example:

{
    "name": "Preprocessor Configuration",
    "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 the includeDirectories field’s value.

Example:

{
    "name": "Include Directories",
    "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:

{
    "name": "Defines",
    "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 Sigasi 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 that are visible to VHDL-2019 conditional analysis directives.

Example:

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