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