SvPortSim.Verilator.Docker (SvPortSim v0.2.0)

Runs Verilator inside Docker for build and lint-only flows.

This module stages SystemVerilog source files, and in build mode a generated C++ wrapper, into a host-side work directory. It then mounts that directory into a Docker container and invokes Verilator.

compile_executable/4 preserves the original executable-producing API and is equivalent to compile/4 with mode: :build. lint/3 and compile/4 with mode: :lint_only run Verilator with --lint-only and do not require or return a wrapper executable.

Summary

Types

build_result()

compile_mode()

compile_result()

lint_result()

Functions

compile(top_module, source_files, wrapper_cpp, opts \\ [])

Runs Verilator through Docker in either build or lint-only mode.

compile_executable(top_module, source_files, wrapper_cpp, opts \\ [])

Compiles a Verilated executable by running Verilator inside Docker.

default_work_dir(top_module)

Returns the default host-side Verilator work directory for top_module.

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

Runs Verilator lint-only validation through Docker.

Types

build_result()

@type build_result() :: %{
  mode: :build,
  top_module: String.t(),
  image: String.t(),
  docker: Path.t(),
  work_dir: Path.t(),
  obj_dir: Path.t(),
  executable: Path.t(),
  command: [String.t()],
  log: String.t()
}

compile_mode()

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

compile_result()

@type compile_result() :: build_result() | lint_result()

lint_result()

@type lint_result() :: %{
  mode: :lint_only,
  top_module: String.t(),
  image: String.t(),
  docker: Path.t(),
  work_dir: Path.t(),
  obj_dir: Path.t(),
  command: [String.t()],
  log: String.t()
}

Functions

compile(top_module, source_files, wrapper_cpp, opts \\ [])

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

Runs Verilator through Docker in either build or lint-only mode.

Options

:mode - :build or :lint_only. Defaults to :build.
:docker_mode - :run_once or :persistent. Defaults to :run_once. Persistent mode uses SvPortSim.Verilator.DockerWorker and docker exec to reuse a long-running container.
:image - Docker image to use. Defaults to "verilator/verilator:latest".
:work_dir - Host-side build directory. Defaults to default_work_dir(top_module). The directory is expanded before use.
:docker - Docker executable path. When omitted, the executable is resolved with DockerAvailability.executable/0.
:check_docker - Whether to check Docker daemon reachability before preparing the workspace and running Verilator. Defaults to true.
:make_jobs - Value passed to Verilator's -j option in build mode. Accepts a non-negative integer or a non-empty string. Defaults to 0.
:extra_args - Additional Verilator arguments. Must be a list of strings. Defaults to [].
:user - Docker user option. Defaults to :current, which attempts to pass the current uid:gid to Docker. Use nil or false to omit --user, or pass a non-empty string such as "1000:1000".
:clean - Whether to remove staged rtl/, cpp/, and obj_dir/ directories before preparing the workspace. Defaults to true.
:verify_executable - Whether to require the expected executable obj_dir/V<top_module> to exist after Docker finishes successfully in build mode. Defaults to true.
:docker_worker - Existing SvPortSim.Verilator.DockerWorker pid or registered name to use when docker_mode: :persistent.
:docker_worker_name - Container and registry name for persistent mode. Defaults to a stable name derived from work_dir.
:docker_worker_cleanup - :manual or :on_exit. Defaults to :manual.

Build mode returns {:ok, build} with :executable. Lint-only mode returns {:ok, lint} without :executable.

compile_executable(top_module, source_files, wrapper_cpp, opts \\ [])

@spec compile_executable(term(), term(), term(), keyword()) ::
  {:ok, build_result()} | {:error, term()}

Compiles a Verilated executable by running Verilator inside Docker.

This function keeps the historical public API stable. It always runs build mode, stages wrapper_cpp, and verifies obj_dir/V<top_module> by default.

default_work_dir(top_module)

@spec default_work_dir(String.t()) :: Path.t()

Returns the default host-side Verilator work directory for top_module.

The returned path is application-local and is currently resolved as:

Application.app_dir(:sv_port_sim, Path.join(["verilator", top_module]))

For example, the default work directory for "Counter" is under the application's verilator/Counter directory.

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

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

Runs Verilator lint-only validation through Docker.

Lint-only mode stages only the SystemVerilog sources, invokes Verilator with --lint-only, and returns {:error, {:verilator_lint_failed, status, log, command}} when Verilator reports diagnostics with a non-zero exit status.