SvPortSim.Compiler (SvPortSim v0.2.0)

Coordinates the high-level build pipeline for generated SystemVerilog modules.

This module is a convenience facade over the lower-level build steps provided by this package:

SvPortSim.Rtl.expand/2 writes in-memory SystemVerilog sources to RTL files.
SvPortSim.Verilator.Wrapper.write/2 or write/3 generates and writes the C++ wrapper source.
SvPortSim.Verilator.Docker.compile/4 validates or builds the generated design through Docker.

compile/3 defaults to mode: :build, preserving the existing behavior that produces a Verilated executable. mode: :lint_only, or the lint/3 helper, runs Verilator in a lighter validation mode that does not require or return a runnable executable.

Summary

Types

compile_mode()

compile_result()

Functions

compile(top_module, sources, opts \\ [])

Compiles or validates SystemVerilog sources through the selected backend.

lint(top_module, sources, opts \\ [])

Validates generated SystemVerilog sources with Verilator lint-only mode.

Types

compile_mode()

@type compile_mode() :: :build | :lint_only

compile_result()

@type compile_result() :: %{
  :top_module => String.t(),
  :mode => compile_mode(),
  :rtl => map(),
  :wrapper => %{file: Path.t()},
  :build => map(),
  optional(:executable) => Path.t()
}

Functions

compile(top_module, sources, opts \\ [])

@spec compile(term(), term(), keyword()) :: {:ok, compile_result()} | {:error, term()}

Compiles or validates SystemVerilog sources through the selected backend.

top_module is the SystemVerilog top-module name. sources is a map from module names to SystemVerilog source strings. The source map is validated and written by SvPortSim.Rtl.expand/2.

Compilation performs the following steps in order:

expands the SystemVerilog source map into RTL files
writes a generated C++ wrapper for top_module
invokes the selected backend in :build or :lint_only mode

The current implementation supports only the Docker backend.

Options

:mode - :build or :lint_only. Defaults to :build.
:backend - Backend to use. Defaults to :docker. Any value other than :docker returns {:error, {:unsupported_backend, backend}}.
:wrapper_dir - Directory where the generated C++ wrapper is written. Defaults to Application.app_dir(:sv_port_sim, Path.join(["wrapper", top_module])). The directory path is expanded before use.
:signal_specs - Optional list of SvPortSim.SignalSpec metadata maps. When present, the generated wrapper includes poke and peek accessors for supported top-level Verilated fields.
:verilator_args - Additional Verilator arguments. These are converted to the Docker backend's :extra_args option. Defaults to [].
:cache - When true, successful backend results are stored in and retrieved from a content-addressed cache. Defaults to false.
:cache_dir - Cache root used when cache: true. Defaults to "_build/sv_port_sim/cache".

All other options are forwarded to SvPortSim.Verilator.Docker.compile/4 when the Docker backend is used. Pipeline-only options such as :backend, :wrapper_dir, :signal_specs, :verilator_args, :cache, and :cache_dir are not forwarded.

Return value

Returns {:ok, result} on success. The returned result map contains:

:top_module - the top-module name passed to this function
:mode - :build or :lint_only
:rtl - the result returned by SvPortSim.Rtl.expand/2
:wrapper - a map containing the generated wrapper file path
:build - the backend build or lint result
:executable - the generated executable path, only in :build mode

Returns {:error, reason} on failure.

lint(top_module, sources, opts \\ [])

@spec lint(term(), term(), keyword()) :: {:ok, compile_result()} | {:error, term()}

Validates generated SystemVerilog sources with Verilator lint-only mode.

This is equivalent to calling compile/3 with mode: :lint_only. The wrapper source is still generated so that signal metadata is validated consistently, but the Docker backend invokes Verilator with --lint-only and the returned result does not contain :executable.