vpi_user.h

   1 #ifndef __vpi_user_H
   2 #define __vpi_user_H
   3 /*
   4  * Copyright (c) 1999-2008 Stephen Williams (steve@icarus.com)
   5  *
   6  *    This source code is free software; you can redistribute it
   7  *    and/or modify it in source code form under the terms of the GNU
   8  *    General Public License as published by the Free Software
   9  *    Foundation; either version 2 of the License, or (at your option)
  10  *    any later version.
  11  *
  12  *    This program is distributed in the hope that it will be useful,
  13  *    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  *    GNU General Public License for more details.
  16  *
  17  *    You should have received a copy of the GNU General Public License
  18  *    along with this program; if not, write to the Free Software
  19  *    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
  20  */
  21
  22
  23 #if defined(__MINGW32__) || defined (__CYGWIN32__)
  24 #  define DLLEXPORT __declspec(dllexport)
  25 #else
  26 #  define DLLEXPORT
  27 #endif
  28
  29 #ifdef __cplusplus
  30 # define EXTERN_C_START extern "C" {
  31 # define EXTERN_C_END }
  32 #else
  33 # define EXTERN_C_START
  34 # define EXTERN_C_END
  35 #endif
  36
  37 #ifndef __GNUC__
  38 # undef  __attribute__
  39 # define __attribute__(x)
  40 #endif
  41
  42 EXTERN_C_START
  43
  44 # include  <stdarg.h>
  45 # include  <stdio.h>
  46 # include  "_pli_types.h"
  47
  48 typedef struct __vpiHandle *vpiHandle;
  49
  50 /*
  51  * This structure is created by the VPI application to provide hooks
  52  * into the application that the compiler/simulator can access.
  53  */
  54 typedef struct t_vpi_systf_data {
  55       PLI_INT32 type;
  56       PLI_INT32 sysfunctype;
  57       const char *tfname;
  58       PLI_INT32 (*calltf)   (PLI_BYTE8*);
  59       PLI_INT32 (*compiletf)(PLI_BYTE8*);
  60       PLI_INT32 (*sizetf)   (PLI_BYTE8*);
  61       PLI_BYTE8 *user_data;
  62 } s_vpi_systf_data, *p_vpi_systf_data;
  63
  64 /* The type in the above structure can have one of the following
  65    values: */
  66 #define vpiSysTask  1
  67 #define vpiSysFunc  2
  68
  69 typedef struct t_vpi_vlog_info
  70 {
  71       PLI_INT32 argc;
  72       char      **argv;
  73       char      *product;
  74       char      *version;
  75 } s_vpi_vlog_info, *p_vpi_vlog_info;
  76
  77
  78 typedef struct t_vpi_time {
  79
  80       /*
  81         Type can be :
  82
  83         vpiScaledRealTime == 1
  84         vpiSimTime        == 2
  85         vpiSuppressTime   == 3
  86       */
  87
  88       PLI_INT32 type;
  89       PLI_UINT32 high;
  90       PLI_UINT32 low;
  91       double real;
  92 } s_vpi_time, *p_vpi_time;
  93
  94 #define vpiScaledRealTime 1
  95 #define vpiSimTime        2
  96 #define vpiSuppressTime   3
  97
  98 typedef struct t_vpi_vecval {
  99       PLI_INT32 aval, bval; /* ab encoding: 00=0, 10=1, 11=X, 01=Z */
 100 } s_vpi_vecval, *p_vpi_vecval;
 101
 102 typedef struct t_vpi_strengthval {
 103       PLI_INT32 logic;
 104       PLI_INT32 s0, s1;
 105 } s_vpi_strengthval, *p_vpi_strengthval;
 106
 107 /*
 108  * This structure holds values that are passed back and forth between
 109  * the simulator and the application.
 110  */
 111 typedef struct t_vpi_value {
 112       PLI_INT32 format;
 113       union {
 114             char      *str;
 115             PLI_INT32 scalar;
 116             PLI_INT32 integer;
 117             double real;
 118             struct t_vpi_time *time;
 119             struct t_vpi_vecval *vector;
 120             struct t_vpi_strengthval *strength;
 121             char      *misc;
 122       } value;
 123 } s_vpi_value, *p_vpi_value;
 124
 125
 126 /*
 127
 128   Conform the IEEE 1364, We add the
 129   Standard vpi_delay structure to
 130   enable the modpath delay values
 131
 132
 133   Conform IEEE 1364, Pg 670 :
 134
 135   The "da" field of the s_vpi_delay
 136   structure shall be a user allocated
 137   array of "s_vpi_time" structure
 138
 139   The array shall store delay values returned
 140   by vpi_get_delay(). The number of elements in
 141   the array shall be determined by
 142
 143   (1) The number of delays to be retrieved
 144       ( normally this is used in vpi_get_delays (..) )
 145   {
 146     (1.1) Setted by "no_of_delays" field
 147
 148     (1.2) For the primitive_object, the no_of_delays
 149         shall be 2 or 3
 150
 151     (1.3) For path_delay object the no_of_delays shall
 152         be 1,2,3,6, 12
 153
 154     (1.4) For timing_check_object, the no_of_delays shall
 155         be match the number of limits existing in the
 156         Time Check
 157
 158     (1.5) For intermodule_path object, the no_of_delays shall
 159         be 2 or 3
 160   }
 161
 162
 163
 164
 165   (2) The "mtm_flag" && "pulsere_flag"
 166
 167
 168   Normally, if you set mtm = X, pulsere = Y
 169   then, you will need allocate (num * no_of_delay)
 170   s_vpi_time elements for 'da' array before calling
 171   the vpi_get/put_delays (..)
 172
 173   ---------------------------------------------------------------------------
 174   |                |                         |                              |
 175   | mtm_flag       | No of s_vpi_time array  |   order in which delay       |
 176   | pulsere_flag   | element required by the |   elements shall be filed    |
 177   |                | s_vpi_delay->da         |                              |
 178   |                |                         |                              |
 179   |----------------|-------------------------|------------------------------|
 180   |                |                         | 1o delay  da[0]--> 1o delay  |
 181   | mtm = false    | no_of_delay             | 2o delay  da[1]--> 2o delay  |
 182   | pulere = false |                         |                              |
 183   |                |                         |                              |
 184   |----------------|-------------------------|------------------------------|
 185   |                |                         | 1o delay  da[0]--> min delay |
 186   | mtm = true     |                         |           da[1]--> typ delay |
 187   | pulere = false | 3*no_of_delay           |           da[2]--> max delay |
 188   |                |                         | 2o delay  da[3]--> min delay |
 189   |                |                         |           da[4]--> typ delay |
 190   |                |                         |           ....               |
 191   |----------------|-------------------------|------------------------------|
 192   |                |                         | 1o delay  da[0]--> delay     |
 193   | mtm = false    |                         |           da[1]--> rej limit |
 194   | pulere = true  | 3*no_of_delay           |           da[2]--> err limit |
 195   |                |                         | 2o delay  da[3]--> delay     |
 196   |                |                         |           da[4]--> rej limit |
 197   |                |                         |           ....               |
 198   |----------------|-------------------------|------------------------------|
 199   |                |                         | 1o delay da[0]--> min delay  |
 200   | mtm = true     |                         |          da[1]--> typ delay  |
 201   | pulere = true  | 9*no_of_delay           |          da[2]--> max delay  |
 202   |                |                         |          da[3]--> min delay  |
 203   |                |                         |          da[4]--> typ delay  |
 204   |                |                         |          da[5]--> max delay  |
 205   |                |                         |          da[6]--> min delay  |
 206   |                |                         |          da[7]--> typ delay  |
 207   |                |                         |          da[8]--> max delay  |
 208   |                |                         | 2o delay da[9]--> min delay  |
 209   |                |                         |          ....                |
 210    -------------------------------------------------------------------------
 211
 212    IMPORTANT :
 213
 214    The delay Structure has to be allocated before passing a pointer to
 215    "vpi_get_delays ( )".
 216
 217 */
 218
 219
 220 typedef struct t_vpi_delay  {
 221       struct t_vpi_time  *da; /* Array of delay data */
 222       PLI_INT32  no_of_delays ;
 223       PLI_INT32  time_type; /* vpiScaledRealTime, vpiSimTime */
 224       PLI_INT32  mtm_flag;
 225       PLI_INT32  append_flag;
 226       PLI_INT32  plusere_flag;
 227 } s_vpi_delay, *p_vpi_delay;
 228
 229
 230
 231
 232
 233 /* These are valid codes for the format of the t_vpi_value structure. */
 234 #define vpiBinStrVal    1
 235 #define vpiOctStrVal    2
 236 #define vpiDecStrVal    3
 237 #define vpiHexStrVal    4
 238 #define vpiScalarVal    5
 239 #define vpiIntVal       6
 240 #define vpiRealVal      7
 241 #define vpiStringVal    8
 242 #define vpiVectorVal    9
 243 #define vpiStrengthVal 10
 244 #define vpiTimeVal     11
 245 #define vpiObjTypeVal  12
 246 #define vpiSuppressVal 13
 247
 248
 249 /* SCALAR VALUES */
 250 #define vpi0 0
 251 #define vpi1 1
 252 #define vpiZ 2
 253 #define vpiX 3
 254 #define vpiH 4
 255 #define vpiL 5
 256 #define vpiDontCare 6
 257
 258 /* STRENGTH VALUES */
 259 #define vpiSupplyDrive  0x80
 260 #define vpiStrongDrive  0x40
 261 #define vpiPullDrive    0x20
 262 #define vpiLargeCharge  0x10
 263 #define vpiWeakDrive    0x08
 264 #define vpiMediumCharge 0x04
 265 #define vpiSmallCharge  0x02
 266 #define vpiHiZ          0x01
 267
 268 /* OBJECT CODES */
 269 #define vpiConstant     7
 270 #define vpiFunction    20
 271 #define vpiIntegerVar  25
 272 #define vpiIterator    27
 273 #define vpiMemory      29
 274 #define vpiMemoryWord  30
 275 #define vpiModPath     31
 276 #define vpiModule      32
 277 #define vpiNamedBegin  33
 278 #define vpiNamedEvent  34
 279 #define vpiNamedFork   35
 280 #define vpiNet         36
 281 #define vpiParameter   41
 282 #define vpiPathTerm    43
 283 #define vpiRealVar     47
 284 #define vpiReg         48
 285 #define vpiSysFuncCall 56
 286 #define vpiSysTaskCall 57
 287 #define vpiTask        59
 288 #define vpiTimeVar     63
 289 #define vpiIndex       78
 290 #define vpiLeftRange   79
 291 #define vpiParent      81
 292 #define vpiRightRange  83
 293 #define vpiScope       84
 294 #define vpiSysTfCall   85
 295 #define vpiArgument    89
 296 #define vpiInternalScope 92
 297 #define vpiModPathIn     95
 298 #define vpiModPathOut    96
 299 #define vpiVariables   100
 300
 301 #define vpiCallback  1000
 302
 303 /* PROPERTIES */
 304 #define vpiUndefined  (-1)
 305 #define vpiType       1
 306 #define vpiName       2
 307 #define vpiFullName   3
 308 #define vpiSize       4
 309 #define vpiFile       5
 310 #define vpiLineNo     6
 311 #define vpiTopModule  7
 312 #define vpiDefName    9
 313 #define vpiTimeUnit      11
 314 #define vpiTimePrecision 12
 315 #define vpiDefFile   15
 316 #define vpiDefLineNo 16
 317 #define vpiNetType   22
 318 #   define vpiWire        1
 319 #define vpiArray     28
 320 #define vpiEdge      36
 321 #   define vpiNoEdge     0x00 /* No edge */
 322 #   define vpiEdge01     0x01 /* 0 --> 1 */
 323 #   define vpiEdge10     0x02 /* 1 --> 0 */
 324 #   define vpiEdge0x     0x04 /* 0 --> x */
 325 #   define vpiEdgex1     0x08 /* x --> 1 */
 326 #   define vpiEdge1x     0x10 /* 1 --> x */
 327 #   define vpiEdgex0     0x20 /* x --> 0 */
 328 #   define vpiPosedge    (vpiEdgex1|vpiEdge01|vpiEdge0x)
 329 #   define vpiNegedge    (vpiEdgex0|vpiEdge10|vpiEdge1x)
 330 #   define vpiAnyEdge    (vpiPosedge|vpiNegedge)
 331 #define vpiConstType 40
 332 #   define vpiDecConst    1
 333 #   define vpiRealConst   2
 334 #   define vpiBinaryConst 3
 335 #   define vpiOctConst    4
 336 #   define vpiHexConst    5
 337 #   define vpiStringConst 6
 338 #define vpiFuncType  44
 339 #   define vpiIntFunc     1
 340 #   define vpiRealFunc    2
 341 #   define vpiTimeFunc    3
 342 #   define vpiSizedFunc   4
 343 #   define vpiSizedSignedFunc 5
 344 #define vpiSysFuncType     vpiFuncType
 345 #   define vpiSysFuncInt   vpiIntFunc
 346 #   define vpiSysFuncReal  vpiRealFunc
 347 #   define vpiSysFuncTime  vpiTimeFunc
 348 #   define vpiSysFuncSized vpiSizedFunc
 349 #define vpiSigned    65
 350 #define vpiExpr      102
 351 /* IVL private properties */
 352 #define _vpiNexusId 0x1000000
 353
 354 /* DELAY MODES */
 355 #define vpiNoDelay            1
 356 #define vpiInertialDelay      2
 357 #define vpiTransportDelay     3
 358 #define vpiPureTransportDelay 4
 359
 360 #define vpiForceFlag   5
 361 #define vpiReleaseFlag 6
 362 #define vpiReturnEvent 0x1000
 363
 364 /* VPI FUNCTIONS */
 365 extern void vpi_register_systf(const struct t_vpi_systf_data*ss);
 366
 367 /* I/O routines */
 368 extern PLI_UINT32 vpi_mcd_open(char *name);
 369 extern PLI_UINT32 vpi_mcd_close(PLI_UINT32 mcd);
 370 extern char      *vpi_mcd_name(PLI_UINT32 mcd);
 371 extern PLI_INT32  vpi_mcd_printf(PLI_UINT32 mcd, const char*fmt, ...)
 372       __attribute__((format (printf,2,3)));
 373
 374 extern PLI_INT32  vpi_printf(const char*fmt, ...)
 375       __attribute__((format (printf,1,2)));
 376
 377 extern PLI_INT32  vpi_vprintf(const char*fmt, va_list ap);
 378 extern PLI_INT32  vpi_mcd_vprintf(PLI_UINT32 mcd, const char*fmt, va_list ap);
 379
 380 extern PLI_INT32  vpi_flush(void);
 381 extern PLI_INT32  vpi_mcd_flush(PLI_UINT32 mcd);
 382
 383 /* proposed extensions */
 384 /*
 385  * These functions are proposed extensions to Verilog, and
 386  * are described by the Verilog PLI task force as issue#347.
 387  *
 388  * The vpi_fopen() function is exactly the same as the $fopen system
 389  * function. That is, it takes a path string and a mode string, and
 390  * opens the file. The result is a 32bit value with bit 31 set, the
 391  * remaining bits made up a small integer to represent the file.
 392  *
 393  * The vpi_get_file(fd) function takes as input a descriptor as
 394  * returned by vpi_fopen or $fopen. Bit 31 must be set. The result
 395  * is the C FILE* that represents the file.
 396  */
 397 extern PLI_INT32 vpi_fopen(const char*name, const char*mode);
 398 extern FILE *vpi_get_file(PLI_INT32 fd);
 399
 400 /*
 401  * support for VPI callback functions.
 402  */
 403 typedef struct t_cb_data {
 404       PLI_INT32 reason;
 405       PLI_INT32 (*cb_rtn)(struct t_cb_data*cb);
 406       vpiHandle obj;
 407       p_vpi_time time;
 408       p_vpi_value value;
 409       PLI_INT32 index;
 410       char      *user_data;
 411 } s_cb_data, *p_cb_data;
 412
 413 #define cbValueChange        1
 414 #define cbStmt               2
 415 #define cbForce              3
 416 #define cbRelease            4
 417 #define cbAtStartOfSimTime   5
 418 #define cbReadWriteSynch     6
 419 #define cbReadOnlySynch      7
 420 #define cbNextSimTime        8
 421 #define cbAfterDelay         9
 422 #define cbEndOfCompile      10
 423 #define cbStartOfSimulation 11
 424 #define cbEndOfSimulation   12
 425 #define cbError             13
 426 #define cbTchkViolation     14
 427 #define cbStartOfSave       15
 428 #define cbEndOfSave         16
 429 #define cbStartOfRestart    17
 430 #define cbEndOfRestart      18
 431 #define cbStartOfReset      19
 432 #define cbEndOfReset        20
 433 #define cbEnterInteractive  21
 434 #define cbExitInteractive   22
 435 #define cbInteractiveScopeChange 23
 436 #define cbUnresolvedSystf   24
 437
 438 extern vpiHandle vpi_register_cb(p_cb_data data);
 439 extern PLI_INT32 vpi_remove_cb(vpiHandle ref);
 440
 441 /*
 442  * This function allows a vpi application to control the simulation
 443  * engine. The operation parameter specifies the function to
 444  * perform. The remaining parameters (if any) are interpreted by the
 445  * operation. The vpi_sim_control definition (now named vpi_control)
 446  * was added to P1364-2000 14 July 1999. See PLI Task Force ID: PTF-161
 447  *
 448  * vpiFinish - perform the $finish operation, as soon as the user
 449  *             function returns. This operation takes a single
 450  *             parameter, a diagnostic exit code.
 451  *
 452  * vpiStop -
 453  * vpiReset -
 454  * vpiSetInteractiveScope -
 455  */
 456 extern void vpi_control(PLI_INT32 operation, ...);
 457 #define vpiStop 1
 458 #define vpiFinish 2
 459 #define vpiReset  3
 460 #define vpiSetInteractiveScope 4
 461
 462 /* vpi_sim_control is the incorrect name for vpi_control. */
 463 extern void vpi_sim_control(PLI_INT32 operation, ...);
 464
 465 extern vpiHandle  vpi_handle(PLI_INT32 type, vpiHandle ref);
 466 extern vpiHandle  vpi_iterate(PLI_INT32 type, vpiHandle ref);
 467 extern vpiHandle  vpi_scan(vpiHandle iter);
 468 extern vpiHandle  vpi_handle_by_index(vpiHandle ref, PLI_INT32 index);
 469 extern vpiHandle  vpi_handle_by_name(const char*name, vpiHandle scope);
 470
 471 extern void  vpi_get_time(vpiHandle obj, s_vpi_time*t);
 472 extern PLI_INT32 vpi_get(int property, vpiHandle ref);
 473 extern char      *vpi_get_str(PLI_INT32 property, vpiHandle ref);
 474 extern void  vpi_get_value(vpiHandle expr, p_vpi_value value);
 475
 476 /*
 477  * This function puts a value into the object referenced by the
 478  * handle. This assumes that the value supports having its value
 479  * written to. The time parameter specifies when the assignment is to
 480  * take place. This allows you to schedule an assignment to happen in
 481  * the future.
 482  *
 483  * The flags value specifies the delay model to use in assigning the
 484  * value. This specifies how the time value is to be used.
 485  *
 486  *  vpiNoDelay -- Set the value immediately. The p_vpi_time parameter
 487  *      may be NULL, in this case. This is like a blocking assignment
 488  *      in behavioral code.
 489  *
 490  *  vpiInertialDelay -- Set the value using the transport delay. The
 491  *      p_vpi_time parameter is required and specifies when the
 492  *      assignment is to take place. This is like a non-blocking
 493  *      assignment in behavioral code.
 494  */
 495 extern vpiHandle vpi_put_value(vpiHandle obj, p_vpi_value value,
 496                                p_vpi_time when, PLI_INT32 flags);
 497
 498 extern PLI_INT32 vpi_free_object(vpiHandle ref);
 499 extern PLI_INT32 vpi_get_vlog_info(p_vpi_vlog_info vlog_info_p);
 500
 501 /*
 502   These Routines will enable the modpath vpiHandle
 503   to read/write delay values
 504 */
 505 extern void vpi_get_delays(vpiHandle expr, p_vpi_delay delays);
 506
 507 extern void vpi_put_delays(vpiHandle expr, p_vpi_delay delays);
 508
 509
 510
 511
 512
 513 /*
 514  * These functions support attaching user data to an instance of a
 515  * system task or function. These functions only apply to
 516  * vpiSysTaskCall or vpiSysFuncCall handles.
 517  */
 518 extern PLI_INT32 vpi_put_userdata(vpiHandle obj, void*data);
 519 extern void*vpi_get_userdata(vpiHandle obj);
 520
 521 /*
 522  * Support for handling errors.
 523  */
 524 typedef struct t_vpi_error_info {
 525       PLI_INT32 state;
 526       PLI_INT32 level;
 527       char      *message;
 528       char      *product;
 529       char      *code;
 530       char      *file;
 531       PLI_INT32 line;
 532 } s_vpi_error_info, *p_vpi_error_info;
 533
 534 /* error_info states */
 535 # define  vpiCompile  1
 536 # define  vpiPLI      2
 537 # define  vpiRun      3
 538
 539 /* error_info levels */
 540 # define  vpiNotice    1
 541 # define  vpiWarning   2
 542 # define  vpiError     3
 543 # define  vpiSystem    4
 544 # define  vpiInternal  5
 545
 546 extern PLI_INT32 vpi_chk_error(p_vpi_error_info info);
 547
 548
 549 /* This is the table of startup routines included in each module. */
 550 extern DLLEXPORT void (*vlog_startup_routines[])();
 551
 552
 553 /*
 554  * ICARUS VERILOG EXTENSIONS
 555  *
 556  * The vpip_* functions are Icarus Verilog extensions. They are not
 557  * standard VPI functions, so use these at your own risk.
 558  *
 559  * The vpip_format_* functions format values in string format in the
 560  * manner of the $display system task.
 561  */
 562
 563   /* Format a scalar a la %v. The str points to a 4byte character
 564      buffer. The value must be a vpiStrengthVal. */
 565 extern void vpip_format_strength(char*str, s_vpi_value*value, unsigned bit);
 566 extern void vpip_set_return_value(int value);
 567
 568 EXTERN_C_END
 569
 570 #endif