vvp/vpi.txt

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