A SvPortSim process owns exactly one simulator transport. The process implementation lives in SvPortSim.Server; this module is the public facade that keeps the stable user-facing API, validates command options, normalizes command bodies, and delegates normalized runtime operations to the server.

In production the default transport opens one external wrapper process with the port framing documented by SvPortSim.Protocol; tests and alternative runtimes may provide their own SvPortSim.Transport implementation.

Public contract

The initial stable public API surface is returned by public_functions/0:

• start_link/1 and start/1
• child_spec/1
• reset/2
• tick/2
• poke/4
• peek/3
• stop/2

Default-argument arities such as reset/1, tick/1, poke/3, peek/2, and stop/1 are exported for convenience.

Runtime commands return {:ok, body} for a successful wrapper response or {:error, error_body} for wrapper-side and Elixir-side failures. Error bodies follow the canonical shape documented by SvPortSim.Protocol and include string keys such as "code", "message", "details", and "fatal". stop/2 is terminal and returns :ok after a successful shutdown.

Options

start_link/1 and start/1 accept these simulation options:

• :executable - path to the generated simulator wrapper executable. This is required when using the default SvPortSim.Transport.Port transport.
• :args - command-line arguments passed to the wrapper executable. Defaults to [].
• :transport - module implementing SvPortSim.Transport. Defaults to SvPortSim.Transport.Port.
• :transport_opts - extra keyword options passed to the transport. Defaults to [].
• :default_timeout - runtime command timeout in milliseconds or :infinity. Defaults to 5_000.

Standard GenServer start options :name, :debug, :spawn_opt, :hibernate_after, and :timeout are also accepted.

Runtime calls accept :timeout to override the instance default. reset/2 accepts :cycles and :reset; tick/2 accepts :cycles and :clock. poke/4 accepts encoded bit-vector values in the shape %{bits: bits, width: width} or %{"bits" => bits, "width" => width}. bits must be a string of 0, 1, x, or z characters whose length equals width.

Examples

iex> defmodule SvPortSim.DocTransport do
...>   @behaviour Elixir.SvPortSim.Transport
...>
...>   def open(_opts), do: {:ok, %{signals: %{}}}
...>
...>   def request(%{"op" => "reset"} = request, state, _timeout) do
...>     body = %{"cycles" => request["body"]["cycles"]}
...>     {:ok, response(request, body), %{state | signals: %{}}}
...>   end
...>
...>   def request(%{"op" => "tick"} = request, state, _timeout) do
...>     body = %{"cycles" => request["body"]["cycles"]}
...>     {:ok, response(request, body), state}
...>   end
...>
...>   def request(%{"op" => "poke"} = request, state, _timeout) do
...>     signal = request["body"]["signal"]
...>     value = request["body"]["value"]
...>     state = %{state | signals: Map.put(state.signals, signal, value)}
...>     {:ok, response(request, %{"signal" => signal}), state}
...>   end
...>
...>   def request(%{"op" => "peek"} = request, state, _timeout) do
...>     signal = request["body"]["signal"]
...>     value = Map.get(state.signals, signal, %{"bits" => "0", "width" => 1})
...>     {:ok, response(request, %{"value" => value}), state}
...>   end
...>
...>   def request(%{"op" => "shutdown"} = request, state, _timeout) do
...>     {:ok, response(request, %{}), state}
...>   end
...>
...>   def close(_state), do: :ok
...>
...>   defp response(request, body) do
...>     %{
...>       "v" => 1,
...>       "id" => request["id"],
...>       "kind" => "response",
...>       "op" => request["op"],
...>       "body" => body
...>     }
...>   end
...> end
iex> {:ok, sim} = Elixir.SvPortSim.start_link(transport: SvPortSim.DocTransport)
iex> Elixir.SvPortSim.reset(sim, cycles: 2)
{:ok, %{"cycles" => 2}}
iex> Elixir.SvPortSim.tick(sim)
{:ok, %{"cycles" => 1}}
iex> Elixir.SvPortSim.poke(sim, "enable", %{bits: "1", width: 1})
{:ok, %{"signal" => "enable"}}
iex> Elixir.SvPortSim.peek(sim, "enable")
{:ok, %{"value" => %{"bits" => "1", "width" => 1}}}
iex> Elixir.SvPortSim.stop(sim)
:ok
iex> Elixir.SvPortSim.start_link([])
{:error, {:missing_required_option, :executable}}
iex> {:reset, 2} in Elixir.SvPortSim.public_functions()
true