7. Making Virtual Peripheral Devices (VPDs)

Virtual Peripheral Devices (VPDs) are a mechanism whereby new and interesting user-define input/output devices can be created and used by TkGate. They can be used to create devices such as TTY Devices, Vending Machine, Robots and any other device that can be imagined.

TkGate handling of VPDs is designed to be user extensible. Users create a VPD by writing a Tcl/Tk script to define the physical behavior of the device, and a Verilog library file containing a stub module that interacts with the Tcl script. The Tcl/Tk script can create its own GUI through which the user can interact.

7.1 Overview of Virtual Peripheral Device Design

Virtual Peripheral Devices are comprised of a Tcl/Tk script file, and a Verilog stub module. The script file implements the graphical interface for the device and handles user interaction. The Verilog stub module encapsulates the behavior of the device into a module that can be included in user circuits. The VPD Tcl/Tk script files are read both from a read-only directory that is part of the TkGate installation, and from a user-defined list of directories that can be specified through the Library Options dialog box. These script files are read at start-up time, so you must restart TkGate if you change the Tcl/Tk portion of a VPD.

Since a Verilog description can contain multiple instances of a VPD, the Tcl script must be written in such a way so as to allow multiple instances of that interface. This is done by giving each instance a unique instance name. The VPD instance name is typically the same as the Verilog instance name of the stub module for the VPD. The fully instantiated Verilog instance name is dot separated path such as "top.bus1.dm1".

7.1.1 Named Channels

Communication between the Tcl-side and Verilog-side of the VPD implementation is performed through a Verga extension to Verilog called a "named channel". A named channel is basically a queue that has a string identifier. TkGate provides Tcl-side and Verilog-side access the named channels allowing data to be passed through the channel. Named channels can be used both to send data from the Tcl side to the Verilog side, and to send data from the Verilog side to the Tcl side.

7.1.2 Direct Execution of Tcl Commands

It is also possible for the Verilog stub module to execute Tcl commands directly using the $tkg$exec() system task provided by Verga. However, use of the $tkg$exec() is restricted due to the fact that allowing arbitrary Tcl commands implies allowing arbitrary shell commands. This means that untrusted circuit files could result in damage to the user's system when simulated. For this reason, TkGate provides the capability of choosing a security policy to control the use this system task through the Security Options dialog box.

Because of the potential security issues and the fact the a user could choose to use a "high" security policy, it is generally recommended that VPD implementers should avoid use of $tkg$exec() and use only named channels when possible.

7.2 Installing VPDs

To install a VPD named name, you must install both the "name.tcl" file containing the Tcl implementation, and the "name.v" file containing the Verilog stub module. You can place these files either in the TkGate home directory, or in a user defined directory. To place them in the TkGate home directory, put the "name.tcl" file in the "vpd" sub-directory, and the "name.v" file in the "vlib" sub-directory.

To place your VPD files a user defined location, you must set the paths for library and VPD files. Open the Library Options dialog box and add the directory containing your "name.v" file to the "Verilog Library Path", and the directory containing your "name.tcl" file to the "VPD () File Path".

The VPD files will be automatically loaded and registered when TkGate starts. To use a VPD, you should open the library manager and load your VPD.

7.3 The Tcl-Side Interface

The Tcl script for a VPD is responsible for creating a window for the device, responding to user input, and communicating with the Verilog stub module.

7.3.1 Basic Concepts

A VPD script is a normal Tcl/Tk script and can execute any of the commands that are available through Tcl/Tk. However, since it is loaded with the rest of the TkGate interface, certain design guidelines should be followed to prevent conflicts between the VPD and TkGate. A Tcl-Side API is provided to enable communication between the Verilog portion and the script portion. The VPD API is defined in a Tcl/TK name-space called "VPD". As such, all of the API commands have the prefix "VPD::".

VPD scripts should begin by executing the VPD::register command to register the name of the VPD. It may then optionally use the VPD::allow (and VPD::disallow) command(s) to register specific commands that are allowed to be executed from the Verilog side using the $tkg$exec() system task if that interface method is used. The body of the VPD should be defined within a name-space having the same name as the registered VPD name. All VPD functions should be defined in that name-space. At a minimum, each VPD is required to provide a "post" method. The " post" method should take an instance name as its first argument, and may optionally define one or more additional arguments. This results in the following recommended structure for a VPD Tcl script: 

VPD::register TTY
VPD::allow TTY::data

namespace eval TTY {
   proc post {name} {
     ...body of post method...
   }

   ...other functions used by TTY VPD... 
}

7.3.2 Writing the post Method

The " post" method is generally responsible for taking the following actions: Note that for some VPDs there may be exceptions to these rules. It is also possible to use Tcl as glue to interface the simulation to a real-world device without using a GUI. For example, one could write a VPD to give a Verilog description the ability to access to the Internet. With such a VPD, the VPD::shutdownnotify command can be used to register a script to execute when the simulation is terminated so as to close any open connections.

An example of a simple post method is given below: 

  proc post {name} {
    variable tty_w

    //
    // Create a VPD window.  The title of the window will be "TTY" followed by the name
    // of the instance.  When the simulation is terminated, the TTY::unpost method
    // will be called.
    //
    set tty_w($name) [VPD::createWindow "TTY $name" -shutdowncommand "TTY::unpost $name"]

    ...build GUI...

    VPD::outsignal $name.TD TTY::TD($name) 
    VPD::insignal $name.RD -command "TTY::data" -format %d
  }
Since there can be multiple instances of a VPD, it is important to keep state information for each instance separate. This can be done by keeping all such state information in Tcl arrays. For example, the VPD::createWindow method automatically chooses a name for the top-level window in which the GUI will be constructed. Instead of keeping the window id in a flat variable such as "$tty_w", the information should be kept in a variable such as " $tty_w($name)" indexed by the name of the VPD instance, "$name".

The VPD::outsignal and VPD::insignal methods are used to link Tcl variables or commands to named channels. In the above example, the named channel $name.TD (where $name is the instance name) is associated with the Tcl variable TTY::TD($name). Any time a value is assigned to that variable, the value is transmitted to the Verilog side of the VPD over the named channel. The named channel $name.RD is associated with the Tcl command "TTY::data". Any time data from the Verilog side is available on the named channel $name.RD, that command is executed with the data received on the channel. The -format switch can be used to specify the formatting of the data.

7.3.3 Tcl/TK Side API for VPDs

TkGate provides the following Tcl-side API for creating VPDs:

CommandDescription
VPD::register name Register a new VPD named name. Registering a VPD allows it to be posted using the Verilog $tkg$post() task.
VPD::allow names... Register Tcl commands that can be executed from the Verilog simulation when running TkGate with medium or lower security. The '*' character can be used as a wildcard.
VPD::disallow names... Register Tcl commands for which execution from the Verilog simulation is explicitly disallowed when running TkGate with medium or higher security. The '*' character can be used as a wildcard.
VPD::isallowed name Test a procedure name to see if it can be executed from the Verilog simulation.
VPD::shutdownnotify script Register a script to be executed when TkGate exits simulation mode. The registration is deleted after executing the script.
VPD::createWindow title [options] Create a top-level window that can be used for a VPD and return the name of the window. The window name is automatically generated. Top-level windows created with this command are automatically destroyed when TkGate exits simulation mode. A command to be executed when the simulator shuts down can be specified with the -shutdowncommand option. The shut-down command does any additional cleanup needed by the VPD besides destroying the window.
VPD::outsignal chan var Cause any value assigned to var to be sent to the simulator over the named channel chan. The channel name is typically formed by using the VPD instance name as a prefix and appending a local name with a dot separator. By default, values assigned to var are interpreted as a decimal integer, but Verilog format constants can also be assigned as well. For example, assigning a value of "8'h3f" would cause the value to be interpreted as the 8-bit hexadecimal value '3F'. The association between the channel and the variable is automatically deleted when TkGate exits simulation mode.
VPD::insignal chan [options] Register an action to be taken when data is available on the named channel chan. Channel names are chosen in the same manner as VPD::outsignal. One or more options are usually given with this command. The -command option takes a Tcl command to be executed when data is received on chan. The value received on the channel is appended to the command before execution. The -variable option indicates a variable to be assigned. Additionally, the -format switch indicates the format in which data should be reported. The format is given as a Verilog style format string such as "%d" for decimal or "%h" for hexadecimal. The association between the channel and the variable is automatically deleted when TkGate exits simulation mode.

7.4 The Verilog-