Python client

A reference Python client is provided with the source repository of Verisocks. It provides an easy way to connect to the Verisocks server and to format and send requests to it in accordance with the defined TCP protocol.

The entire client is encapsulated into the Verisocks class, which can easily be instantiated as in the following example:

from verisocks.verisocks import Verisocks

vs = Verisocks("127.0.0.1", 5100)
vs.connect()
vs.run("for_time", time=3.2, time_unit="us")
vs.close()

The Verisocks class comes with proper context manager methods, allowing a safer, more pythonic, way to instantiate it. The context manager will automatically connect to the socket and close it when done. The code of the previous example can thus be equivalently written as:

from verisocks.verisocks import Verisocks

with Verisocks("127.0.0.1", 5100) as vs:
    vs.run("for_time", time=3.2, time_unit="us")

Python client API documentation

class verisocks.verisocks.Verisocks(host='127.0.0.1', port=5100, timeout=120.0, connect_trials=10, connect_delay=0.05)

Verisocks client class.

Parameters:

host (str) – Server host IP address, default=”127.0.0.1”
port (int) – Server port number, default=5100
timeout (float) – Socket timeout (base value), in seconds (default=120)
connect_trials (int) – Number of consecutive connections to be attempted when the method connect() is being used. This value can be overriden by the method’s own trials argument.
connect_delay (float) – Delay to be applied before attempting a new connection trial when the method connect() is being used. This value can be overriden by the method’s own delay argument.

Note

For certain methods, a specific timeout value can be passed as argument. If a value (other than None) is provided, the socket timeout will be modified only temprorarily and then restored to the timeout value provided as argument at the class instantiation.

close(): Close socket connection if still open.

connect(trials=None, delay=None)

Connect to server socket.

If the client is already connected to a server socket, nothing happens. Otherwise, the client attempts to connect to the server as defined by the address and port provided to the class constructor. The method will apply a delay prior each connection trial and will retry a number of times if unsuccessful.

Parameters:

trials (int) – Maximum number of connection trials to be attempted. If None, the value of the connect_trials argument passed to the constructor is being used.
delay (float) – Delay to be applied prior each connection trial. If None, the value of the connect_delay argument passed to the constructor is being used.

Raises:

ConnectionError – All the successive connection trials have been unsucessful

exit(): Sends an exit command to the Verisocks server that gives back control to the simulator and closes the Verisocks server socket. The simulation runs to its end without having the possibility to take the control back from the simulator anymore. The connection is closed as well by the function.

finish(timeout=None): Sends a finish command to the Verisocks server that terminates the simulation (and therefore also closes the Verisocks server itself). The connection is closed as well by the function as a clean-up.

flush(): Flush RX and TX buffers.

get(sel, path='')

Sends a get command request to the Verisocks server.

Equivalent to send_cmd("get", ...). This commands can be used to obtain different pieces of information from the Verisocks server.

Parameters:

sel (str) – Selects which is the returned information.
path (str) – If sel is "value" or "type", path to the desired verilog object for which the value or type is to be returned.

Note

The argument sel can take the following values:

"sim_info": Gets the simulator information, returned with the keywords "product" and "version".
"sim_time": Gets the simulator current time, returned with the keywords "time", in seconds.
"value": Gets the value for a verilog object.
"type": Gets the VPI type value for a verilog object.

Returns:: Content of returned message
Return type:: JSON object

info(value)

Sends an info command to the Verisocks server.

This is a shortcut function, which is equivalent to send_cmd("info", ...). This command is used to send any text to the Verisocks server, which will then be streamed out to the VPI standard output.

Parameters:: value (str) – Text to be sent to the VPI stdout
Returns:: Content of returned message
Return type:: JSON object

read(num_trials=10, timeout=None)

Proceed to read and scan returned TCP messages

Parameters:

num_trials (int) – Maximum number of trials. Default=10.
timeout (float) – Timeout in seconds (default=None). If None, the base value as defined within the class constructor applies.

Returns:

Status. True if successful, False if error.

Return type:

bool

run(cb, **kwargs)

Sends a run command request to the Verisocks server.

Equivalent to send_cmd("run", cb=cb, ...). This command gives the focus back to the simulator and lets it run until the specified callback condition is met (see arguments).

Parameters:: cb (str) – Callback type.
Keyword Arguments:: timeout (float) – Socket timeout configuration value in seconds. If None (default), the class instance default value is used.
Returns:: Content of returned message
Return type:: JSON object

Note

The parameter cb can be either:

"for_time": run for a given amount of time
"until_time": run until a specified time
"until_change": run until a specific value changes
"to_next": run until the beginning of the next time step

If cb is "for_time" or "until_time", the following keyword arguments are further expected:

time (float): Time value
time_unit (str): Time unit (s, ms, us, ns, ps or fs). Be aware that depending on the simulator time resolution, the provided time value may be truncated.

If cb is "until_change", the following keyword argument(s) are further expected:

path (str): Path to verilog object used for the callback
value (number): Condition on the verilog object’s value for the callback to be executed. This argument is not required if the path corresponds to a named event.

If cb is "to_next", no further keyword argument is required.

send(**cmd)

Sends a message with a JSON content.

This command will accept and use any command content defined as keyword arguments (e.g. cmd="get", sel="sim_info"). This content will directly be used as the sent TCP command content.

Keyword Arguments:: timeout (float) – Socket timeout configuration value in seconds. If None (default), the class instance default value is used.
Returns:: Content of returned message.
Return type:: JSON object

send_cmd(command, **kwargs)

Sends a command. Equivalent to send(command=command, ...).

Parameters:

command (str) – Command name (e.g. "get")
**kwargs – Command keyword arguments (e.g. sel="sim_info")

Keyword Arguments:

timeout (float) – Socket timeout configuration value in seconds. If None (default), the class instance default value is used.

Returns:

Content of returned message

Return type:

JSON object

set(path, **kwargs)

Sends a set command request to the Verisocks server.

Equivalent to send_cmd("set", path=path, **kwargs). This commands sets the value of a verilog object as defined by its path.

Parameters:

path (str) – Path to the verilog object.

Keyword Arguments:

value (int, list) – Value to be set. If the path corresponds to a verilog named event, this argument is not required. If the path corresponds to a verilog memory array, this argument needs to be provided as a list of the same length.
timeout (float) – Socket timeout configuration value in seconds. If None (default), the class instance default value is used.

Returns:

Content of returned message

Return type:

JSON object

stop(timeout=None)

Sends a stop command to the Verisocks server.

The "stop" command stops the simulation. The Verisocks server socket is not closed, but the simulation has to be restarted for any new request to be processed.

Parameters:: timeout (int, None) – Timeout in seconds to apply for the execution of the command.

write(all=True)

Writes/sends the current content of the TX buffer to the socket.

Parameters:: all (bool) – If True (default), sends all queued message. Otherwise, it only sends the oldest queued message in the buffer.

exception verisocks.verisocks.VerisocksError: Base class for exceptions in Verisocks

class verisocks.verisocks.VsRxState(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enumerated states for the RX state machine

Possible values are:

RX_INIT: Starting state

RX_PRE_HDR: RX message pre-header has been scanned

RX_HDR: RX message header has been scanned

RX_DONE: RX message content has been scanned

ERROR: Error state

Miscellaneous utilitaries

The module verisocks.utils is a collection of miscellaneous utilitaries and helper functions to ease setting up simulations using Verisocks.

verisocks.utils.find_free_port()

Find a free port on localhost

The implementation for this function is not very elegant, but it does the job… It uses the property of socket.socket.bind() method to bind the socket to a randomly-assigned free port when provided a ('', 0) address argument. Using socket.socket.getsockname() is then used to retrieve the corresponding port number. Since the bound socket is closed within the function, it is assumed that the same port number should also be free again; this is where the weakness of this method lies, since race conditions cannot be fully excluded.

verisocks.utils.setup_sim(vpi_libpath, *src_files, cwd='.', vvp_filepath=None, vvp_logpath='vvp.log', ivl_exec=None, ivl_args=None, vvp_exec=None, vvp_args=None, vvp_postargs=None, capture_output=True)

Set up Icarus simulation by elaborating the design with iverilog and launching the simulation with vvp. Uses setup_sim_run() to run the concatenated commands and arguments.

Parameters:

vpi_libpath (str) – Path to the compiled Verisocks VPI library.
src_files (str) – Paths to all (verilog) source files to use for the simulation. All files have to be added as separate arguments.
cwd (str) – Reference path to be used for all paths provided as relative paths.
vvp_filepath (str) – Path to the elaborated VVP file (iverilog output). If None (default), “sim.vvp” will be used.
vvp_logpath (str) – Path to a simulation logfile. Default=”vvp.log”. If None, no logfile shall be created.
ivl_exec (str) – Path to iverilog executable (absolute path). If None (default), it is assumed to be defined in the system path.
ivl_args (str, list(str)) – Arguments to iverilog executable.
vvp_exec (str) – Path to vvp executable (absolute path). If None (default), it is assumed to be defined in the system path.
vvp_args (list(str)) – Arguments to vvp executable.
vvp_postargs (str, list(str)) – (Post-)arguments to vvp executable. In order to dump waveforms to an FST file, this should be configured as “-fst”.
capture_output (bool) – Defines if stdout and stderr output are “captured” (i.e. not visible).

Returns:

subprocess.Popen

verisocks.utils.setup_sim_run(elab_cmd, sim_cmd, capture_output=True)

Run simulation setup commands.

This command is e.g. used by setup_sim() with elaboration and simulation commands formatted according to the provided arguments.

Parameters:

elab_cmd (list) – Elaboration command. It has to be provided as a list of command and arguments (see subprocess documentation). If None, this step is skipped.
sim_cmd (list) – Simulation command. It has to be provided as a list of command and arguments (see subprocess documentation). This command is mandatory and cannot be None.
capture_output (bool) – Defines if stdout and stderr output are “captured” (i.e. not visible).

Returns:

subprocess.Popen