/**********************************************************************
 * VPI Utility Examples -- PLI application using VPI routines
 *
 * C source for functions to access handles and properties of system 
 * task/function arguments.
 *
 * Usage: 
 *   numargs = PLIbook_numargs_vpi();
 *     Returns the number of system task/function arguments.
 *
 *   arg_handle = PLIbook_getarg_handle_vpi(arg_index_number);
 *     Returns a handke for a system task/function argument,
 *     using the index number of the argument, beginning with 1.
 *
 *   arg_val = PLIbook_getarg_intval_vpi(arg_index_number);
 *     Returns a value as an int for a system task/function argument,
 *     using the index number of the argument, beginning with 1.
 *
 *   arg_val = PLIbook_getarg_realval_vpi(arg_index_number);
 *     Returns a value as a double for a system task/function arg,
 *     using the index number of the argument, beginning with 1.
 *
 *   arg_val = PLIbook_getarg_stringval_vpi(arg_index_number);
 *     Returns a value as a string pointer for a system task/func arg,
 *     using the index number of the argument, beginning with 1.
 *
 *   string_pointer = PLIbook_vpi_get_str(property, object_handle);
 *     Returns a value of a string property, trapping a NULL return.
 *
 *   PLIbook_set_vpiworkarea(systf_handle, value);
 *     Stores a value in a work area that is unique to each instance
 *     of a system task/function.
 *
 *   value = PLIbook_get_vpiworkarea(systf_handle);
 *     Retreives the value stored in the work area for a specific
 *     instance of a system task/function.
 *
 *   string_pointer = PLIbook_fetch_type_str_vpi(type_constant);
 *     Returns the constant name for a type or fulltype property.
 * 
 * For the book, "The Verilog PLI Handbook" by Stuart Sutherland
 *  Book copyright 1999, Kluwer Academic Publishers, Norwell, MA, USA
 *   Contact: www.wkap.il
 *  Example copyright 1998, Sutherland HDL Inc, Portland, Oregon, USA
 *   Contact: www.sutherland.com or (503) 692-0898
 *********************************************************************/

#include <stdlib.h>     /* ANSI C standard library */
#include <stdio.h>      /* ANSI C standard input/output library */
#include "vpi_user.h"   /* IEEE 1364 PLI VPI routine library  */

#define PLIbookDebug /* comment out to omit verbose debug messages */

/* Prototypes of the utility applications */
int        PLIbook_numargs_vpi();
vpiHandle  PLIbook_getarg_handle_vpi(int argNum);
int        PLIbook_getarg_intval_vpi(int argNum);
double     PLIbook_getarg_realval_vpi(int argNum);
char      *PLIbook_getarg_stringval_vpi(int argNum);
char      *PLIbook_vpi_get_str(int type, vpiHandle obj_h);
void       PLIbook_set_vpiworkarea(vpiHandle systf_h, char *data);
char      *PLIbook_get_vpiworkarea(vpiHandle systf_h);
char      *PLIbook_fetch_type_str_vpi(int type);


/**********************************************************************
 * PLIbook_numargs_vpi()
 * Counts the number of system task/function arguments.  Similar to
 * tf_nump().
 *********************************************************************/
int PLIbook_numargs_vpi()
{
  vpiHandle systf_h, arg_itr, arg_h;
  int tfnum = 0;

  #ifdef PLIbookDebug
    s_vpi_error_info err;  /* structure for error handling */
  #endif

  systf_h = vpi_handle(vpiSysTfCall, NULL);
  #ifdef PLIbookDebug /* if error, generate verbose debug message */
    if (vpi_chk_error(&err)) {
      vpi_printf("ERROR: PLIbook_numargs_vpi() could not obtain handle to systf call\n");
      vpi_printf("File %s, Line %d: %s\n",
                 err.file, err.line, err.message);
    }
  #else /* if error, generate brief error message */
    if (systf_h == NULL)
      vpi_printf("ERROR: PLIbook_numargs_vpi() could not obtain handle to systf call\n");
  #endif

  arg_itr = vpi_iterate(vpiArgument, systf_h);
  #ifdef PLIbookDebug /* if error, generate verbose debug message */
    if (vpi_chk_error(&err)) {
      vpi_printf("ERROR: PLIbook_numargs_vpi() could not obtain iterator to systf args\n");
      vpi_printf("File %s, Line %d: %s\n",
                 err.file, err.line, err.message);
    }
  #else /* if error, generate brief error message */
    if (systf_h == NULL)
      vpi_printf("ERROR: PLIbook_numargs_vpi() could not obtain iterator to systf args\n");
  #endif

  while (arg_h = vpi_scan(arg_itr) ) {
    tfnum++;
  }

  return(tfnum);
}


/**********************************************************************
 * PLIbook_getarg_handle_vpi() -- Version 2
 * Obtain a handle to a system task/function argument, using the
 * argument index number.  Similar to acc_handle_tfarg().
 * This version is more efficient than Version 1 (which follows),
 * because this version allocates memory and stores the task arg
 * handles so that vpi_iterate() and vpi_scan() do not need to be
 * called each time this application is called.
 *********************************************************************/
vpiHandle PLIbook_getarg_handle_vpi(int argNum)
{
  vpiHandle systf_h, arg_itr, arg_h;
  int i, tfnum;
  vpiHandle *arg_handle_array; /* array pointer to store arg handles */
  
  #ifdef PLIbookDebug
    s_vpi_error_info err;  /* structure for error handling */
  #endif

  if (argNum < 1) {
    vpi_printf("ERROR: PLIbook_getarg_handle_vpi() argNum invalid\n");
    return(NULL);
  }
  
  systf_h = vpi_handle(vpiSysTfCall, NULL);
  #ifdef PLIbookDebug /* if error, generate verbose debug message */
    if (vpi_chk_error(&err)) {
      vpi_printf("ERROR: PLIbook_getarg_handle_vpi() could not obtain handle to systf call\n");
      vpi_printf("File %s, Line %d: %s\n",
                 err.file, err.line, err.message);
    }
  #else /* if error, generate brief error message */
    if (systf_h == NULL) {
      vpi_printf("ERROR: PLIbook_getarg_handle_vpi() could not obtain handle to systf call\n");
      return(NULL);
    }
  #endif

  /* see if already have an array with all argument handles */
  arg_handle_array = (vpiHandle *)PLIbook_get_vpiworkarea(systf_h);
  if (arg_handle_array == NULL) {
    /* allocate an array and store all argument handles in the array */
    #ifdef PLIbookDebug /* generate verbose debug message */
      vpi_printf("PLIbook_getarg_handle_vpi() is allocating workarea storage for task args\n"); 
    #endif
    tfnum = PLIbook_numargs_vpi();
    arg_handle_array = (vpiHandle *)malloc(sizeof(vpiHandle) * tfnum);
    PLIbook_set_vpiworkarea(systf_h, (char *)arg_handle_array);

    arg_itr = vpi_iterate(vpiArgument, systf_h);
    #ifdef PLIbookDebug /* if error, generate verbose debug message */
      if (vpi_chk_error(&err)) {
        vpi_printf("ERROR: PLIbook_getarg_handle_vpi() could not obtain iterator to systf args\n");
        vpi_printf("File %s, Line %d: %s\n",
                   err.file, err.line, err.message);
      }
    #else /* if error, generate brief error message */
      if (systf_h == NULL) {
        vpi_printf("ERROR: PLIbook_getarg_handle_vpi() could not obtain iterator to systf args\n");
        return(NULL);
      }
    #endif
    for (i=0; i<=tfnum; i++) {
      arg_h = vpi_scan(arg_itr);
      #ifdef PLIbookDebug /* if error, generate verbose debug message */
        if (vpi_chk_error(&err)) {
          vpi_printf("ERROR: PLIbook_getarg_handle_vpi() could not obtain handle to systf arg %d\n", i);
          vpi_printf("File %s, Line %d: %s\n",
                     err.file, err.line, err.message);
        }
      #endif
      arg_handle_array[i] = arg_h;
    }
    vpi_free_object(arg_itr); /* free iterator -- didn't scan all args */
  }

  arg_h = (vpiHandle)arg_handle_array[argNum-1]; /* array starts with 0, argnums with 1 */
  return(arg_h);
}


/**********************************************************************
 * PLIbook_getarg_handle_vpi() -- Version 1
 * Obtain a handle to a system task/function argument, using the
 * argument index number.  Similar to acc_handle_tfarg().
 * The method used in this version is not as efficient as version 2
 * because this method must call vpi_iterate() and vpi_scan() for the 
 * system task args each time this application is called.
 *********************************************************************/
vpiHandle PLIbook_getarg_handle_vpi_version1(int argNum)
{
  vpiHandle systf_h, arg_itr, arg_h;
  int i;
  #ifdef PLIbookDebug
    s_vpi_error_info err;  /* structure for error handling */
  #endif

  if (argNum < 1) {
    vpi_printf("ERROR: PLIbook_getarg_handle_vpi() argNum invalid\n");
    return(NULL);
  }

  systf_h = vpi_handle(vpiSysTfCall, NULL);
  #ifdef PLIbookDebug /* if error, generate verbose debug message */
    if (vpi_chk_error(&err)) {
      vpi_printf("ERROR: PLIbook_getarg_handle_vpi() could not obtain handle to systf call\n");
      vpi_printf("File %s, Line %d: %s\n",
                 err.file, err.line, err.message);
    }
  #else /* if error, generate brief error message */
    if (systf_h == NULL) {
      vpi_printf("ERROR: PLIbook_getarg_handle_vpi() could not obtain handle to systf call\n");
      return(NULL);
    }
  #endif

  arg_itr = vpi_iterate(vpiArgument, systf_h);
  #ifdef PLIbookDebug /* if error, generate verbose debug message */
    if (vpi_chk_error(&err)) {
      vpi_printf("ERROR: PLIbook_getarg_handle_vpi() could not obtain iterator to systf args\n");
      vpi_printf("File %s, Line %d: %s\n",
                 err.file, err.line, err.message);
    }
  #else /* if error, generate brief error message */
    if (systf_h == NULL) {
      vpi_printf("ERROR: PLIbook_getarg_handle_vpi() could not obtain iterator to systf args\n");
      return(NULL);
    }
  #endif

  for (i=1; i<=argNum; i++) {
    arg_h = vpi_scan(arg_itr);
    #ifdef PLIbookDebug /* if error, generate verbose debug message */
      if (vpi_chk_error(&err)) {
        vpi_printf("ERROR: PLIbook_getarg_handle_vpi() could not obtain handle to systf arg %d\n", i);
        vpi_printf("File %s, Line %d: %s\n",
                   err.file, err.line, err.message);
      }
    #endif
    if (arg_h == NULL) {
      vpi_printf("ERROR: PLIbook_getarg_handle_vpi() systf arg %d out-of-range\n",
                 argNum);
      return(NULL);
    }
  }
  vpi_free_object(arg_itr); /* free iterator -- didn't scan all args */

  return(arg_h);
}


/**********************************************************************
 * PLIbook_getarg_intval_vpi()
 * Return the value of a system task/function argument as an integer.
 * Similar to acc_fetch_tfarg_int()
 *********************************************************************/
int PLIbook_getarg_intval_vpi(int argNum)
{
  vpiHandle arg_h;
  s_vpi_value argVal;
  #ifdef PLIbookDebug
    s_vpi_error_info err;  /* structure for error handling */
  #endif
 
  arg_h = PLIbook_getarg_handle_vpi(argNum);
  if (arg_h == NULL) {
    vpi_printf("ERROR: PLIbook_getarg_intval_vpi() could not obtain arg handle\n");
    return(0);
  }
  argVal.format = vpiIntVal;
  vpi_get_value(arg_h, &argVal);
  #ifdef PLIbookDebug /* if error, generate verbose debug message */
    if (vpi_chk_error(&err)) {
      vpi_printf("ERROR: PLIbook_getarg_intval_vpi() could not obtain arg value\n");
      vpi_printf("File %s, Line %d: %s\n",
                 err.file, err.line, err.message);
      return(0);
    }
  #endif

  return(argVal.value.integer);
}