Loader
Finds and loads Verilog or SystemVerilog source files—generally
the first step toward using VL to work with a hardware design.
Introduction
Most Verilog designs involve many files spread out across multiple
directories. To really load a high-level module top, we typically need
to:
- start by parsing its file, say top.v or top.sv, then
- figure out which supporting descriptions are used within top and
- use a search procedure to load these supporting descriptions from library
directories.
VL's top-level function for loading Verilog files, vl-load,
implements such a scheme. It has various options (see vl-loadconfig)
that allow you to specify the search paths and extensions to use when looking
for files, etc. A typical command to load a design might look something like
this:
(defconsts (*loadresult* state)
(vl::vl-load (vl::make-vl-loadconfig
:start-files (list "top.v")
:search-path (list "/path/to/lib1"
"/path/to/lib2")
:include-dirs (list "/path/to/includes1"
"/path/to/includes2")
:defines (make-vl-initial-defines "FORMAL")
:edition :system-verilog-2012)))
The resulting *loadresult* will be a vl-loadresult, which among
other things will contain the vl-design that has been loaded. The next
step after loading is typically to annotate the design using vl-annotate-design, and then to further processing it in whatever way is
suitable for your particular flow.
Supported Constructs and Workarounds
For general background on what VL supports, see supported-constructs.
A common problem when working with a Verilog or SystemVerilog design is that
you want to process the design with many tools, and these tools may not all
support quite the same constructs. One common way to work around these issues
is with preprocessor directives. For instance, you might write
something like:
`ifndef FORMAL
... something VL can't handle ...
`else
... replacement for VL ...
`endif
Note that vl-load does not automatically set up any such `define
directives by default, but it's easy to give custom defines in your vl-loadconfig.
Besides the preprocessor, VL also supports a special comment syntax that can
be used to hide VL-specific code from other tools:
//+VL single-line version
/*+VL multi-line version */
For instance, if you need your modules to work with an old Verilog
implementation that doesn't support Verilog-2005 style attributes, you might
write something like:
//+VL (* my_attribute *)
assign foo = bar;
VL will still parse the (* my_attribute *) part since it is in this
special comment. VL also provides a special, more concise syntax for
attributes:
//@VL my_attribute
Note that you can also disable these special comments with the strictp
option on your vl-loadconfig.
Subtopics
- Preprocessor
- Limited preprocessor for Verilog.
- Vl-loadconfig
- Options for how to load Verilog modules.
- Vl-loadstate
- Internal state object used throughout the VL loading routines.
- Lexer
- A lexer for Verilog and SystemVerilog.
- Parser
- A parser for a subset of Verilog and SystemVerilog.
- Vl-load-merge-descriptions
- Merge newly found Verilog descriptions with previously loaded
descriptions, warning about any multiply defined descriptions.
- Vl-find-basename/extension
- Alternative to vl-find-file that can take a list of
extensions.
- Vl-load-file
- Main function for loading a single Verilog file.
- Vl-loadresult
- Return value from vl-load.
- Scope-of-defines
- How VL and other tools handle the scope of `defines.
- Vl-find-file
- Determine where to load a file from, given its (absolute or relative)
name and a list of directories to search.
- Vl-flush-out-descriptions
- Attempt to find and load any missing modules.
- Vl-description
- Representation of an arbitrary, top-level element.
- Vl-read-file
- Read an entire file into a list of extended characters.
- Vl-includeskips-report-gather
- Vl-load-main
- Top level interface for loading Verilog sources.
- Extended-characters
- Characters with additional annotations.
- Vl-load
- Wrapper for vl-load-main that also reports errors or (with
some configuration) can print other information.
- Vl-load-description
- Try to load a description from the search path.
- Vl-descriptions-left-to-load
- Determine which descriptions we still need to load.
- Inject-warnings
- Mechanism for attaching warnings to particular modules or
other design elements.
- Vl-preprocess-debug
- Vl-write-preprocessor-debug-file
- Vl-read-file-report-gather
- Vl-load-descriptions
- Extend vl-load-description to try to load a list of descriptions.
- Vl-load-files
- Load a list of files.
- Translate-off
- Warnings about comments like // synopsys translate_off.
- Vl-load-read-file-hook
- Vl-read-file-report
- Vl-loadstate-pad
- Prefix for lines produced by the loader.
- Vl-load-summary
- Print summary information (e.g., warnings, numbers of modules loaded,
etc.) after modules have been loaded.
- Vl-collect-modules-from-descriptions
- Vl-loadstate->warnings
- Vl-iskips-report
- Vl-descriptionlist
- A list of vl-description-p objects.
