docs/wiki/geda-icarus_vpi_within_vvp.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html>
   4 <head>
   5   <title></title>
   6   <link rel="stylesheet" media="screen" type="text/css" href="./style.css" />
   7   <link rel="stylesheet" media="screen" type="text/css" href="./design.css" />
   8   <link rel="stylesheet" media="print" type="text/css" href="./print.css" />
   9
  10   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  11 </head>
  12 <body>
  13
  14
  15 <h1 class="sectionedit783"><a name="vpi_within_vvp" id="vpi_within_vvp">VPI_within_VVP</a></h1>
  16 <div class="level1">
  17 <pre class="code">/*
  18  * Copyright (c) 2001 Stephen Williams (steve@icarus.com)
  19  *
  20  *  $Id: vpi.txt,v 1.7 2003/02/09 23:33:26 steve Exp $
  21  */
  22
  23
  24 VPI WITHIN VVP
  25
  26 System tasks and functions in Verilog are implemented in Icarus
  27 Verilog by C routines written with VPI. This implies that the vvp
  28 engine must provide at least a subset of the Verilog VPI
  29 interface. The minimalist concepts of vvp, however, make the method
  30 less then obvious.
  31
  32 Within a Verilog design, there is a more or less fixed web of
  33 vpiHandles that is the design database as is available to VPI
  34 functions. The Verilog standard defines quite a lot of types, but the
  35 vvp only implements the ones it needs. The VPI web is added into the
  36 design using special pseudo-ops that create the needed objects.
  37
  38
  39 LOADING VPI MODULES
  40
  41 The vvp runtime loads VPI modules at runtime before the parser reads
  42 in the source files. This gives the modules a chance to register tasks
  43 and functions before the source is compiled. This allows the compiler
  44 to resolve references to system tasks and system functions to a
  45 vpiHandle at compile time. References to missing tasks/function can
  46 thus be caught before the simulation is run.
  47
  48      NOTE: This also, miraculously, allows for some minimal support of
  49      the compiletf call. From the perspective of VPI code, compilation
  50      of the VVP source is not unlike compilation of the original
  51      Verilog.
  52
  53 The handle that the vvp threads have to the VPI are the vpiHandles of
  54 the system tasks and functions. The %vpi_call instruction, once compiled,
  55 carries the vpiHandle of the system task.
  56
  57
  58 SYSTEM TASK CALLS
  59
  60 A system task call invokes a VPI routine, and makes available to that
  61 routine the arguments to the system task. The called routine gets
  62 access to the system task call by calling back the VPI requesting the
  63 handle. It uses the handle, in turn, to get hold of the operands for
  64 the task.
  65
  66 All that vvp needs to know about a system task call is the handle of
  67 the system task definitions (created by the vpi_register_systf
  68 function) and the arguments of the actual call. The arguments are
  69 tricky because the list has no bound, even though each particular call
  70 in the Verilog source has a specific set of parameters.
  71
  72 Since each call takes a fixed number of parameters, the input source
  73 can include in the statement the list of arguments. The argument list
  74 will not fit in a single generated instruction, but a vpiHandle that
  75 refers to a vpiSysTfCall does. Therefore, the compiler can take the
  76 long argument list and form a vpiSysTaskCall object. The generated
  77 instruction then only needs to be a %vpi_call with the single parameter
  78 that is the vpiHandle for the call.
  79
  80
  81 SYSTEM FUNCTION CALLS
  82
  83 System function calls are similar to system tasks. The only
  84 differences are that all the arguments are input only, and there is a
  85 single magic output that is the return value. The same %vpi_call can
  86 even be used to call a function.
  87
  88 System functions, like system tasks, can only be called from thread
  89 code. However, they can appear in expressions, even when that
  90 expression is entirely structural. The desired effect is achieved by
  91 writing a wrapper thread that calls the function when inputs change,
  92 and that writes the output into the containing expression.
  93
  94
  95 SYSTEM TASK/FUNCTION ARGUMENTS
  96
  97 The arguments to each system task or call are not stored in the
  98 instruction op-code, but in the vpiSysTfCall object that the compiler
  99 creates and that the %vpi_call instruction ultimately refers to. All
 100 the arguments must be some sort of object that can be represented by a
 101 vpiHandle at compile time.
 102
 103 Arguments are handled at compile time by the parser, which uses the
 104 argument_list rule to build a list of vpiHandle objects. Each argument
 105 in the argument_list invokes whatever function is appropriate for the
 106 token in order to make a vpiHandle object for the argument_list. When
 107 all this is done, an array of vpiHandles is passed to code to create a
 108 vpiSysTfCall object that has all that is needed to make the call.
 109
 110
 111 SCOPES
 112
 113 VPI can access scopes as objects of type vpiScope. Scopes have names
 114 and can also contain other sub-scopes, all of which the VPI function
 115 can access by the vpiInternalScope reference. Therefore, the run-time
 116 needs to form a tree of scopes into which other scoped VPI objects are
 117 placed.
 118
 119 A scope is created with a .scope directive, like so:
 120
 121         &lt;label&gt; .scope &quot;name&quot; [, &lt;parent&gt;];
 122                 .timescale &lt;units&gt;;
 123
 124 The scope takes a string name as the first parameter. If there is an
 125 additional parameter, it is a label of the directive for the parent
 126 scope. Scopes that have no parent are root scopes. It is an error to
 127 declare a scope with the same name more then once in a parent scope.
 128
 129 The name string given when creating the scope is the basename for the
 130 scope. The vvp automatically constructs full names from the scope
 131 hierarchy, and runtime VPI code can access that full name with the
 132 vpiFullname reference.
 133
 134 The .timescale directive changes the scope units from the simulation
 135 precision to the specified precision. The .timescale directive affects
 136 the current scope.
 137
 138 Objects that place themselves in a scope place themselves in the
 139 current scope. The current scope is the one that was last mentioned by
 140 a .scope directive. If the wrong scope is current, the label on a
 141 scope directive can be used to resume a scope. The syntax works like
 142 this:
 143
 144                 .scope &lt;symbol&gt;;
 145
 146 In this case, the &lt;symbol&gt; is the label of a previous scope directive,
 147 and is used to identify the scope to be resumed. A scope resume
 148 directive cannot have a label.
 149
 150
 151 VARIABLES
 152
 153 Reg vectors (scalars are vectors of length 1) are created by .var
 154 statements in the source. The .var statement includes the declared
 155 name of the variable, and the indices of the MSB and LSB of the
 156 vector. The vpiHandle is then created with this information, and the
 157 vpi_ipoint_t pointer to the LSB functor of the variable. VPI programs
 158 access the vector through the vpiHandle and related functions. The VPI
 159 code gets access to the declared indices.
 160
 161 The VPI interface to variable (vpiReg objects) uses the MSB and LSB
 162 values that the user defined to describe the dimensions of the
 163 object.
 164
 165 /*
 166  * Copyright (c) 2001 Stephen Williams (steve@icarus.com)
 167  *
 168  *    This source code is free software; you can redistribute it
 169  *    and/or modify it in source code form under the terms of the GNU
 170  *    General Public License as published by the Free Software
 171  *    Foundation; either version 2 of the License, or (at your option)
 172  *    any later version.
 173  *
 174  *    This program is distributed in the hope that it will be useful,
 175  *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 176  *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 177  *    GNU General Public License for more details.
 178  *
 179  *    You should have received a copy of the GNU General Public License
 180  *    along with this program; if not, write to the Free Software
 181  *    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 182  */</pre>
 183
 184 </div>
 185 </body>
 186 </html>