veriuser.h

   1 #ifndef __veriuser_H
   2 #define __veriuser_H
   3 /*
   4  * Copyright (c) 2002-2003 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 #ifdef HAVE_CVS_IDENT
  22 #ident "$Id: veriuser.h,v 1.34 2003/10/10 02:57:45 steve Exp $"
  23 #endif
  24
  25 /*
  26  * This header file contains the definitions and declarations needed
  27  * by an Icarus Verilog user using tf_ routines.
  28  *
  29  * NOTE 1: Icarus Verilog does not directly support tf_ routines. This
  30  * header file defines a tf_ compatibility later. The functions that
  31  * are implemented here are actually implemented using VPI routines.
  32  *
  33  * NOTE 2: The routines and definitions of the tf_ library were
  34  * clearly not designed to account for C++, or even ANSI-C. This
  35  * header file attempts to fix these problems in a source code
  36  * compatible way. In the end, though, it is not completely
  37  * possible. Instead, users should not use this or the acc_user.h
  38  * header files or functions in new applications, and instead use the
  39  * more modern vpi_user.h and VPI functions.
  40  *
  41  * This API is provided by Icarus Verilog only to support legacy software.
  42  */
  43
  44
  45 #ifdef __cplusplus
  46 # define EXTERN_C_START extern "C" {
  47 # define EXTERN_C_END }
  48 #else
  49 # define EXTERN_C_START
  50 # define EXTERN_C_END
  51 #endif
  52
  53 #ifndef __GNUC__
  54 # undef  __attribute__
  55 # define __attribute__(x)
  56 #endif
  57
  58 EXTERN_C_START
  59
  60 # include  "_pli_types.h"
  61
  62 /*
  63  * defines for tf_message
  64  */
  65 #define ERR_MESSAGE 1
  66 #define ERR_WARNING 2
  67 #define ERR_ERROR   3
  68 #define ERR_INTERNAL 4
  69 #define ERR_SYSTEM   5
  70
  71 /*
  72  * These are some defines for backwards compatibility. They should not
  73  * be used in new code.
  74  */
  75 #ifndef TRUE
  76 # define TRUE 1
  77 #endif
  78 #ifndef FALSE
  79 # define FALSE 0
  80 #endif
  81 #ifndef __cplusplus
  82 # ifndef true
  83 #  define true 1
  84 # endif
  85 # ifndef false
  86 #  define false 0
  87 # endif
  88 # ifndef bool
  89 #  define bool int
  90 # endif
  91 #endif
  92
  93 /*
  94  * structure for veriusertfs array
  95  */
  96 typedef struct t_tfcell
  97 {
  98       short type;               /* usertask|userfunction|userrealfunction */
  99       short data;               /* data passed to user routine */
 100       int   (*checktf)(int user_data, int reason);
 101       int   (*sizetf)(int user_data, int reason);
 102       int   (*calltf)(int user_data, int reason);
 103       int   (*misctf)(int user_data, int reason, int paramvc);
 104       char  *tfname;            /* name of the system task/function */
 105       int   forwref;            /* usually set to 1 */
 106       char  *tfveritool;        /* usually ignored */
 107       char  *tferrmessage;      /* usually ignored */
 108       char  reserved[20];            /* reserved */
 109 } s_tfcell, *p_tfcell;
 110
 111 /*
 112  * Normal PLI1.0 modules export a veriusertfs array that contains all
 113  * the function definitions for use by the simulator. The user code is
 114  * expected to supply that array. The method of export varies amongst
 115  * Verilog simulators, but at least one vendor gets a pointer to the
 116  * veriusertfs array by calling a boot function that takes no
 117  * arguments and returns a pointer to the table.
 118  *
 119  * The Icarus Verilog bootstrap process is a little bit different, and
 120  * is described in the vpi_user.h header file. However, a fairly
 121  * simple adaptation to your application fixes it so that it
 122  * automatically boots with Icarus Verilog.
 123  *
 124  * The trick is to write a vlog_startup_routine that calls the
 125  * veriusertfs_register_table function. A simple example:
 126  *
 127  *   static struct s_tfcell my_veriusertfs_table[] = {
 128  *          [... table entries, null terminated ...]
 129  *   };
 130  *
 131  *   // Cadence compatibility
 132  *   struct s_tfcell* my_bootstrap(void)
 133  *   { return my_veriusertfs_table; }
 134  *
 135  *   // Icarus Verilog compatibility
 136  *   static void veriusertfs_register(void)
 137  *   {
 138  *       veriusertfs_register_table(my_veriusertfs_table);
 139  *   }
 140  *   void (*vlog_startup_routines[])() = { &veriusertfs_register, 0 };
 141  *
 142  * The veriusertfs_register function and vlog_startup_routines table
 143  * are specific to Icarus Verilog, and arrange for automatic loading
 144  * of the PLI1 application. The vvp program will treat this as any
 145  * other VPI module.
 146  *
 147  * By structuring the bootstrap process in this manner, it is
 148  * plausible to make source code compatibility with a variety of
 149  * Verilog simulators.
 150  *
 151  * NOTE: The cadpli module of Icarus Verilog also makes it possible to
 152  * be *binary* compatible with other simulators. Create the
 153  * my_bootstrap function and leave out the vlog_startup_routines, then
 154  * use the "-mcadpli" module to load it in compatibility mode.
 155  */
 156 extern s_tfcell veriusertfs[];
 157 extern void veriusertfs_register_table(p_tfcell vtable);
 158
 159 #define usertask 1
 160 #define userfunction 2
 161 #define userrealfunction 3
 162
 163 /* callback reasons */
 164 #define reason_checktf 1
 165 #define reason_calltf  3
 166 #define reason_paramvc 7
 167 #define reason_synch   8
 168 #define REASON_SYNCH   reason_synch
 169 #define reason_finish  9
 170 #define reason_reactivate 10
 171 #define REASON_REACTIVATE reason_reactivate
 172 #define reason_rosynch 11
 173 #define REASON_ROSYNCH reason_rosynch
 174 #define reason_endofcompile 16
 175
 176 /* These are values returned by tf_typep */
 177 #define tf_nullparam    0
 178 #define TF_NULLPARAM    tf_nullparam
 179 #define tf_string       1
 180 #define TF_STRING       tf_string
 181 #define tf_readonly     10
 182 #define TF_READONLY     tf_readonly
 183 #define tf_readwrite    11
 184 #define TF_READWRITE    tf_readwrite
 185 #define tf_rwbitselect  12
 186 #define TF_RWBITSELECT  tf_rwbitselect
 187 #define tf_rwpartselect 13
 188 #define TF_RWPARTSELECT tf_rwpartselect
 189 #define tf_rwmemselect  14
 190 #define TF_RWMEMSELECT  tf_rwmemselect
 191 #define tf_readonlyreal 15
 192 #define TF_READONLYREAL tf_readonlyreal
 193 #define tf_readwritereal 16
 194 #define TF_READWRITEREAD tf_readwritereal
 195
 196 typedef struct t_tfnodeinfo {
 197       PLI_INT16 node_type;
 198       PLI_INT16 padding;
 199       union {
 200             struct t_vecval *vecval_p;
 201             struct t_strengthval *strengthval_p;
 202             PLI_BYTE8 *memoryval_p;
 203             double *read_value_p;
 204       } node_value;
 205       char* node_symbol;
 206       PLI_INT32 node_ngroups;
 207       PLI_INT32 node_vec_size;
 208       PLI_INT32 node_sign;
 209       PLI_INT32 node_ms_index;
 210       PLI_INT32 node_ls_index;
 211       PLI_INT32 node_mem_size;
 212       PLI_INT32 node_lhs_element;
 213       PLI_INT32 node_rhs_element;
 214       PLI_INT32*node_handle;
 215 } s_tfnodeinfo, *p_tfnodeinfo;
 216
 217 /* values used in the node_type of the tfnodeinfo structure. */
 218 #define tf_null_node    100
 219 #define TF_NULL_NODE    tf_null_node
 220 #define tf_reg_node     101
 221 #define TF_REG_NODE     tf_reg_node
 222 #define tf_integer_node 102
 223 #define TF_INTEGER_NODE tf_integer_node
 224 #define tf_time_node    103
 225 #define TF_TIME_NODE    tf_time_node
 226 #define tf_netvector_node 104
 227 #define TF_NETVECTOR_NODE tf_netvector_node
 228 #define tf_netscalar_node 105
 229 #define TF_NETSCALAR_NODE tf_netscalar_node
 230 #define tf_memory_node    106
 231 #define TF_MEMORY_NODE    tf_memory_node
 232 #define tf_real_node      107
 233 #define TF_REAL_NODE      tf_real_node
 234
 235 /* Structure used by the tf_exprinfo function. */
 236 typedef struct t_tfexprinfo {
 237       PLI_INT16 expr_type;
 238       PLI_INT16 padding;
 239       struct t_vecval*expr_value_p;
 240       double real_value;
 241       char*expr_string;
 242       PLI_INT32 expr_ngroups;
 243       PLI_INT32 expr_vec_size;
 244       PLI_INT32 expr_sign;
 245       PLI_INT32 expr_lhs_select;
 246       PLI_INT32 expr_rhs_select;
 247 } s_tfexprinfo, *p_tfexprinfo;
 248
 249
 250 /* Extern functions from the library. */
 251 extern void io_printf (const char *, ...)
 252       __attribute__((format (printf,1,2)));
 253 extern char* mc_scan_plusargs(char*plusarg);
 254
 255 extern int tf_asynchoff(void);
 256 extern int tf_asynchon(void);
 257
 258 extern int tf_dofinish(void);
 259
 260 extern int tf_dostop(void);
 261
 262 extern void tf_error(const char*, ...)
 263       __attribute__((format (printf,1,2)));
 264
 265 extern struct t_tfexprinfo* tf_exprinfo(PLI_INT32 a, struct t_tfexprinfo*ip);
 266
 267 extern char* tf_getcstringp(int nparam);
 268
 269 extern PLI_BYTE8* tf_getinstance(void);
 270
 271 extern int tf_getlongp(int*aof_highvalue, int pnum);
 272
 273 extern PLI_INT32 tf_getp(PLI_INT32);
 274 extern PLI_INT32 tf_igetp(PLI_INT32, void*);
 275
 276 extern double tf_getrealp(PLI_INT32);
 277 extern double tf_igetrealp(PLI_INT32, void*);
 278
 279 extern char *tf_strgetp(PLI_INT32, PLI_INT32);
 280 extern char *tf_istrgetp(PLI_INT32, PLI_INT32, void*);
 281
 282 extern char *tf_strgettime(void);
 283 extern PLI_INT32 tf_gettime(void);
 284
 285 extern PLI_INT32 tf_getlongtime(PLI_INT32*);
 286 extern PLI_INT32 tf_igetlongtime(PLI_INT32*, void*);
 287
 288 extern void tf_scale_longdelay(void*,PLI_INT32,PLI_INT32,PLI_INT32*,PLI_INT32*);
 289 extern void tf_unscale_longdelay(void*,PLI_INT32,PLI_INT32,PLI_INT32*,PLI_INT32*);
 290 extern void tf_scale_realdelay(void*,double,double*);
 291 extern void tf_unscale_realdelay(void*,double,double*);
 292
 293 extern PLI_INT32 tf_gettimeprecision(void);
 294 extern PLI_INT32 tf_igettimeprecision(void*);
 295
 296 extern PLI_INT32 tf_gettimeunit(void);
 297 extern PLI_INT32 tf_igettimeunit(void*);
 298
 299 extern PLI_BYTE8* tf_getworkarea(void);
 300
 301 extern PLI_INT32 tf_message(PLI_INT32 level, char*facility,
 302                             char*messno, char*fmt, ...)
 303       __attribute__((format (printf,4,5)));
 304
 305 extern void tf_multiply_long(PLI_INT32*aof_low1, PLI_INT32*aof_high1,
 306                              PLI_INT32 aof_low2, PLI_INT32 aof_high2);
 307 extern void tf_real_to_long(double real, PLI_INT32*low, PLI_INT32*high);
 308 extern void tf_long_to_real(PLI_INT32 low, PLI_INT32 high, double *real);
 309
 310 extern PLI_INT32 tf_nump(void);
 311 extern PLI_INT32 tf_inump(void*);
 312
 313 /* IEEE1364 NOTE: tf_putlongp is listed as returning in in the header
 314    file shown in the standard, but as returning void in the detailed
 315    description of the function. So I call it void. */
 316 extern void tf_putlongp(int pnum, int lowvalue, int highvalue);
 317
 318 extern PLI_INT32 tf_putp(PLI_INT32, PLI_INT32);
 319 extern PLI_INT32 tf_iputp(PLI_INT32, PLI_INT32, void*);
 320
 321 extern PLI_INT32 tf_putrealp(PLI_INT32, double);
 322 extern PLI_INT32 tf_iputrealp(PLI_INT32, double, void*);
 323
 324 /* Activate the misctf function after a delay. The units are of the
 325    current scope. The tf_isetdelay variant specifies a particular
 326    system task instance to use as the context for the
 327    units. tf_getinstance gets that value. */
 328 extern int tf_setdelay(PLI_INT32 delay);
 329 extern int tf_isetdelay(PLI_INT32 delay, void* sys);
 330
 331 /* IEEE1364 NOTE: tf_setworkarea is listed as taking a PLI_BYTE8*, but
 332    that is silly, it really takes any kind of pointer. Taking void* is
 333    compatible with those who pass a PLI_BYTE8*. */
 334 extern PLI_INT32 tf_setworkarea(void*workarea);
 335
 336 /* Return the complete, hierarchical name of the current scope. The
 337    current scope is the scope containing the currently running system
 338    task call. */
 339 extern char* tf_spname(void);
 340
 341 extern char* tf_mipname(void);
 342 extern char* tf_imipname(void*);
 343
 344 extern PLI_INT32 tf_synchronize(void);
 345 extern PLI_INT32 tf_isynchronize(void* sys);
 346
 347 extern PLI_INT32 tf_rosynchronize(void);
 348 extern PLI_INT32 tf_irosynchronize(void* sys);
 349
 350 extern PLI_INT32 tf_setrealdelay(double realdelay);
 351 extern PLI_INT32 tf_isetrealdelay(double realdelay, void*inst);
 352
 353 extern PLI_INT32 tf_typep(PLI_INT32 narg);
 354
 355 extern void tf_warning(const char*, ...)
 356       __attribute__((format (printf,1,2)));
 357
 358 EXTERN_C_END
 359
 360 /*
 361  * $Log: veriuser.h,v $
 362  * Revision 1.34  2003/10/10 02:57:45  steve
 363  *  Some PLI1 stubs.
 364  *
 365  * Revision 1.33  2003/06/13 19:23:41  steve
 366  *  Add a bunch more PLI1 routines.
 367  *
 368  * Revision 1.32  2003/06/04 01:56:20  steve
 369  * 1) Adds configure logic to clean up compiler warnings
 370  * 2) adds acc_compare_handle, acc_fetch_range, acc_next_scope and
 371  *    tf_isetrealdelay, acc_handle_scope
 372  * 3) makes acc_next reentrant
 373  * 4) adds basic vpiWire type support
 374  * 5) fills in some acc_object_of_type() and acc_fetch_{full}type()
 375  * 6) add vpiLeftRange/RigthRange to signals
 376  *
 377  * Revision 1.31  2003/05/30 04:22:13  steve
 378  *  Add tf_strgetp functions.
 379  *
 380  * Revision 1.30  2003/05/30 04:18:31  steve
 381  *  Add acc_next function.
 382  *
 383  * Revision 1.29  2003/05/30 04:01:55  steve
 384  *  Add tf_scale_longdelay.
 385  *
 386  * Revision 1.28  2003/05/29 03:46:21  steve
 387  *  Add tf_getp/putp support for integers
 388  *  and real valued arguments.
 389  *
 390  *  Add tf_mipname function.
 391  *
 392  * Revision 1.27  2003/05/28 03:38:05  steve
 393  *  Implement tf_inump
 394  *
 395  * Revision 1.26  2003/05/28 03:14:20  steve
 396  *  Missing time related declarations.
 397  *
 398  * Revision 1.25  2003/05/18 00:16:35  steve
 399  *  Add PLI_TRACE tracing of PLI1 modules.
 400  *
 401  *  Add tf_isetdelay and friends, and add
 402  *  callback return values for acc_vcl support.
 403  *
 404  * Revision 1.24  2003/04/23 15:01:29  steve
 405  *  Add tf_synchronize and tf_multiply_long.
 406  *
 407  * Revision 1.23  2003/04/12 18:57:13  steve
 408  *  More acc_ function stubs.
 409  *
 410  * Revision 1.22  2003/03/13 04:35:09  steve
 411  *  Add a bunch of new acc_ and tf_ functions.
 412  *
 413  * Revision 1.21  2003/02/26 01:25:51  steve
 414  *  Document new PLI1 bootstrap interface.
 415  *
 416  * Revision 1.20  2003/02/17 06:39:47  steve
 417  *  Add at least minimal implementations for several
 418  *  acc_ functions. Add support for standard ACC
 419  *  string handling.
 420  *
 421  *  Add the _pli_types.h header file to carry the
 422  *  IEEE1364-2001 standard PLI type declarations.
 423  *
 424  * Revision 1.19  2003/02/16 02:23:22  steve
 425  *  Change the IV veriusertfs_register to accept table pointers.
 426  *
 427  * Revision 1.18  2002/12/19 21:37:04  steve
 428  *  Add tf_message, tf_get/setworkarea, and
 429  *  ty_typep functions, along with defines
 430  *  related to these functions.
 431  *
 432  * Revision 1.17  2002/08/12 01:35:01  steve
 433  *  conditional ident string using autoconfig.
 434  *
 435  * Revision 1.16  2002/06/11 03:29:14  steve
 436  *  Get tf_asynchon/off name right.
 437  *
 438  * Revision 1.15  2002/06/07 16:21:12  steve
 439  *  Add tf_putlongp and tf_putp.
 440  */
 441 #endif