Supported VHPI Functions

vhpi_assert()

Formal Definition

Reports an error message. Complete description: IEEE Std 1076™-2008 §23.2

Synopsis

int vhpi_assert(vhpiSeverityT severity, char *formatmsg, ...);

Description

The vhpi_assert function is an equivalent to the VHDL report statement. The formatmsg argument is a format string that may contain conversion codes defined for the C printf function in ISO/IEC 9899:1999/Cor 1:2001. The format string and subsequent arguments to the vhpi_assert function are interpreted as it is specified in ISO/IEC 9899:1999/Cor 1:2001 for the C printf function to form a formatted character string that corresponds to the string expression value in the VHDL report statement. The severity argument corresponds to the severity expression value in the report statement. The allowed values for the severity argument are: vhpiNote, vhpiWarning, vhpiError, vhpiFailure, vhpiSystem and vhpiInternal.

Returned value

0 if operation completes without errors; or 1 otherwise.

Example

In the following example, the VHPI model registers a callback that is triggered when an event on the m_var signal occurs.

vhpiHandleT hnd = vhpi_handle_by_name("top.m_var", NULL);
vhpiCbDataT *cbDataAction;
vhpiValueT *Value;
vhpiTimeT *Time;
cbDataAction = (vhpiCbDataT*) malloc ( sizeof(vhpiCbDataT) );
Value = (vhpiValueT*) malloc ( sizeof(vhpiValueT) );
Time  = (vhpiTimeT*)  malloc ( sizeof(vhpiTimeT) );

Value->format = vhpiIntVal;
Value->bufSize = 0;
Value->value.intgs = 0;
cbDataAction->time = Time;                
cbDataAction->value = Value;
cbDataAction->user_data  = NULL;
cbDataAction->cb_rtn = val_change;
cbDataAction->reason = vhpiCbValueChange; 
cbDataAction->obj = hnd;  
  
vhpi_register_cb (cbDataAction, vhpiReturnCb);

The val_change callback routine is listed below. It contains the vhpi_assert function call that is executed when the value m_var exceeds the value MAX_VALUE. Since the severity parameter is set to the vhpiError value, the assertion will be reported as an error message.

PLI_VOID val_change (const struct vhpiCbDataS * cbDatap) {
const int mx = MAX_VALUE;
vhpiValueT *value;
value = (vhpiValueT*) malloc ( sizeof(vhpiValueT) );
value->format    = vhpiIntVal;
value->bufSize     = 0;  
value =  cbDatap->value;

if (value->value.intg > mx)
  vhpi_assert(vhpiFailure, "Signal exceeded value %d (m_var is %d)", mx, value->value.intg);  
else vhpi_printf("m_var is %d\n", value->value.intg);
}

The VHPI procedure assertion_ex that registers the callback is executed at the beginning of the proc1 process, so that the every occurrence of an event on the m_var signal within that process triggers the execution of the callback routine.

begin 
proc1: process 
begin            
  assertion_ex;        
  m_var <= 2;  wait for 1 ps; 
  m_var <= 3;  wait for 1 ps; 
  m_var <= 4;  wait for 1 ps; 
  m_var <= 7;  wait for 1 ps; 
  m_var <= 10;wait for 1 ps; 
  m_var <= 11;wait for 1 ps;                 
  wait;
end process;

Assuming the MAX_VALUE is 3, the following output message will be displayed:

# VHPI: m_var is 2
# VHPI: m_var is 3
# VHPI: Signal exceeded value 3 (m_var is 4)
# VHPI: Signal exceeded value 3 (m_var is 7)
# VHPI: Signal exceeded value 3 (m_var is 10)
# VHPI: Signal exceeded value 3 (m_var is 11)

vhpi_check_error()

Formal Definition

Retrieves information about an error raised by a VHPI function.

Complete description: IEEE Std 1076™-2008 §23.3

Synopsis

int vhpi_check_error (vhpiErrorInfoT *error_info_p);

Description

The vhpi_check_error function checks whether the most previous call to a VHPI function returned an error. The error_info_p argument is either a pointer to an error information structure or NULL. If the value of error_info_p is not NULL, the vhpi_check_error function writes information about the error into the structure. Before the vhpi_check_error call, the memory for the error information structure should be allocated by the VHPI program.

If no error was raised by the previous call to a VHPI function and the value of the error_info_p is not NULL, the values written into structure fields are not specified. Otherwise, if an error occurred and the value of the error_info_p is not NULL, the members of the structure are written as follows:

  • severity: The severity level of the error.

  • message: A pointer to a string with the error message.

  • str: A pointer to an implementation-defined content.

  • file: A pointer to a string that contains the name of the VHDL source file containing the VHDL item that corresponds to the handle passed to the VHPI function that raised the error. It has NULL value if such a file cannot be specified.

  • line: A number of line in the file containing the VHDL item corresponding to the VHPI handle that was passed to a function that raised the error. It contains -1 value if such a line cannot be specified.

Returned value

0 if no error occurred on the previous call to a VHPI function, or 1 otherwise.

Example

The following VHPI program will display the error message if the vhpi_put_value() function preceding the vhpi_check_error() function returns an error code.

vhpiHandleT hnd  = vhpi_handle_by_name("top.val_err", NULL);  
val->value.real = 100;      
val->format = vhpiRealVal;
vhpi_put_value(hnd, val, vhpiDeposit);
if (vhpi_check_error(err)) 
{  
  switch (err->severity)
  {
    case vhpiWarning: {err_str = "vhpiWarning:"; break;}      
    case vhpiError: {err_str = "vhpiError:"; break;}
    case vhpiFailure: {err_str = "vhpiFailure:"; break;}
    case vhpiInternal: {err_str = "vhpiInternal:"; break;}  
    case vhpiSystem: {err_str = "vhpiSystem:"; break;}
    default: {err_str = "Error:"; break;}
  }
  vhpi_printf("%s %s \n", err_str, err->message);
}

Assuming that the VHDL signal top.val_err is of a different type then the real type specified in the vhpiValueT value structure, the function vhpi_put_value will return the error code 2, and the message created on the basis of values returned by the vhpi_check_error() function will be as follows:

# VHPI: vhpiWarning: vhpi_put_value: Format vhpiRealVal does not fit type of return value.

vhpi_compare_handles()

Formal Definition

Compares handles. Complete description: IEEE Std 1076™-2008 §23.4

Synopsis

int vhpi_compare_handles (vhpiHandleT handle1, vhpiHandleT handle2);

Description

The function determines whether the handles specified with the handle1 and handle2 arguments refer to the same object.

Returned value

1 if the handle1 and handle2 arguments refer to the same object; or 0 otherwise.

Example

The following VHPI program iterates through all the handles referring to the signals in the region specified with the hnd_s handle and compares these handles to the hnd_j handle. If the handles match, the program displays the name and the value of the signal referred to by the handles.

vhpiHandleT hnd_s = vhpi_handle_by_name("top", NULL);
vhpiHandleT hnd_j = vhpi_handle_by_name("top.s1", NULL);
vhpiHandleT hnd_r;  
vhpiHandleT hnd_i = vhpi_iterator(vhpiSigDecls, hnd_s);
while (hnd_r = vhpi_scan(hnd_i)) {
  if (vhpi_compare_handles(hnd_r,hnd_j)) {
    vhpi_get_value(hnd_r, value);
    vhpi_printf( "%s = %d\n",vhpi_get_str(vhpiFullNameP, hnd_r), value->value.intg );        
  }            

vhpi_control()

Formal Definition

Issues a control request to the VHPI tool. Complete description: IEEE Std 1076™-2008 §23.2

Synopsis

int vhpi_control (vhpiSimControlT command);

Description

The command argument is of the enumeration vhpiSimControlT type specifying the request for a control action and can be of the one of the following values: vhpiStop or vhpiFinish. If the command argument has vhpiStop value, the vhpi_control function suspends the simulation and then accepts further actions from the user or the command source. The vhpiFinish value triggers the termination of the simulation.

Returned value

0 if operation completes without errors; or 1 otherwise.

Example

In the following example, the vhpi_control function finishes the simulation if the hnd_r handle which is set on subsequent elements of the object referred to by the hnd_i handle is equal to the hnd_j handle.

while (hnd_r = vhpi_scan(hnd_i)) {
  if (vhpi_compare_handles(hnd_r,hnd_j)) {
    vhpi_get_value(hnd_r, value);
    vhpi_control(vhpiFinish);          
  }            
}

vhpi_create()

Formal Definition

Creates an object of class processStmt, driver, driverCollection, or anyCollection; or appends an object to a collection. Complete description: IEEE Std 1076™-2008 §23.6

Synopsis

vhpiHandleT vhpi_create (vhpiClassKindT kind, vhpiHandleT handle1, vhpiHandleT handle2);

Description

The kind argument specifies the class of the created object. Assigning the vhpiProcessStmtk value to this argument specifies that the object created by the vhpi_create() function is of the processStmt class. In this case, the handle1 argument refers to an object of class archBody whose IsForeign property is set to vhpiTrue, and the handle2 argument is NULL.

If the kind argument is of the vhpiDriverK value, the function creates an object of the driver class associated with the object of class basicSignal referred to by handle1. Optionally, if the handle2 argument is not NULL, a newly-created object may be associated with an object of the processStmt class specified by the handle2 argument.

If the kind argument has the vhpiDriverCollectionK value, the function creates a new collection of drivers or appends the drivers to already created collection. If handle1 refers to NULL, a new object of driverCollection is created and the driver or collection of drivers is appended to that object. If handle1 is not NULL, the function appends one or more drivers to an object of the driverCollection class referred to by handle1. The handle2 refers to an object of the Driver or DriverCollection class and specifies a driver or a collection of drivers to be appended. The drivers are appended in the same sequence as they were ordered in the collection pointed by handle2.

The vhpiAnyCollectionK value of the kind object specifies that a created object will be a collection of the anyCollection class. If handle1 refers to NULL, the function creates a new object of anyCollection and appends one or more members to the newly created object. If handle1 is not NULL, the function appends one or more members to an object of the anyCollection class referred to by handle1. In both cases, if handle2 refers to an object of the collection class, all its members are appended to the object of anyCollection class in the order consistent with the order of members in the object pointed by handle2. If handle2 refers to an object of a class different than the collection class, that object is the single object appended to the collection pointed by the handle1 argument.

Returned value

A handle to the newly created object or collection if the operation completes without error; or NULL otherwise.

Example

In the example below, the vhpi_create function is used to create a process in a foreign architecture specified with the foreignHdl handle and to create drivers for each signal declared in that architecture.

vhpiHandleT arr[DRIVERS];

procHdl = vhpi_create(vhpiProcessStmtK, foreignHdl, NULL);
itrHdl = vhpi_iterator(vhpiSigDecls, foreignHdl);
while (sigHdl = vhpi_scan(itrHdl)) {
  drivHdl = vhpi_create(vhpiDriverK, sigHdl, procHdl);
  arr[i] = drivHdl;
  i++;
}

vhpi_disable_cb()

Formal Definition

Disables a registered callback.

Complete description: IEEE Std 1076™-2008 §23.7

Synopsis

int vhpi_disable_cb (vhpiHandleT cb_obj);

Description

The vhpi_disable_cb() function disables a callback, and thus, prevents the execution of the callback function calls when the callback trigger event occurs. The cb_obj argument is a handle to the callback to be disabled.

Returned value

The function returns 0 on success and 1 on failure.

Related functions

Use vhpi_enable_cb() to re-enable the callback.

Example

The below VHPI program sets the callbacks that are sensitive for a value change on all the signals in the specified hierarchy region. The vhpi_disable_cb function is used to disable callbacks that triggered the execution of the callback routine a specified number of times.

The vhpi_disable_cb function is placed in the callback routine and executed when the value that counts the number of the routine executions (cb_counter[cbDatap->obj]) exceeds the value referred to by the hnd handle. Since in the callback routine, there is no direct access to the handle to the callback that caused the current execution of the routine, but there is an access to a handle to a signal on which the callback was set, the argument of the vhpi_disable_cb function which is a handle to a callback is specified as an element of an associative array that associates the handle to the signal with the handle to the callback registered on that signal.

PLI_VOID register_cb ( const struct vhpiCbDataS* cb_p ) {    

vhpiHandleT hnd    = vhpi_handle_by_name("top", NULL);
vhpiHandleT hndcb;

vhpiCbDataT      cbDataAction;
vhpiValueT       *Value;
vhpiTimeT        *Time;
            
Value = (vhpiValueT*) malloc ( sizeof(vhpiValueT) );
Time  = (vhpiTimeT*)  malloc ( sizeof(vhpiTimeT) );

Value->format            = vhpiIntVal;
Value->bufSize           = 0;
Value->value.intgs       = 0;
cbDataAction.cb_rtn      = cb_routine;
cbDataAction.reason      = vhpiCbValueChange; 
cbDataAction.time        = Time;                
cbDataAction.value       = Value;
cbDataAction.user_data   = NULL;
        
vhpiHandleT hnditr    = vhpi_iterator(vhpiSigDecls, hnd); 
  while ( vhpiHandleT hndByIdx = vhpi_scan (hnditr) ) {
          cbDataAction.obj = hndByIdx;      
          hndcb = vhpi_register_cb (&cbDataAction, vhpiReturnCb);                                      
      mymap[hndByIdx]=hndcb;              
      cb_counter[hndByIdx] = 1;
    }

The associative array (mymap) is filled with data during the execution of the register_cb function that registers the callbacks on all the signals in the specified hierarchy region. In the register_cb function, there is also another associative array indexed with the handles to signals. The other array is of the integer type and its elements are used to count the number of callback executions that are caused by changes on the particular VHDL signals. The values in this array are incremented at the end of the callback routine execution.

The associative array declarations are shown below. Each of them has to be declared globally since the arrays have to be visible in the scopes of the both functions: register_cb and cb_routine.

std::map<vhpiHandleT,vhpiHandleT> mymap; 
std::map<vhpiHandleT,int> cb_counter;

The VHDL architecture in which the foreign model is registered is shown below. The value denoting the upper limit of callback executions can be specified as a generic of an entity so it could be set separately for each instance that uses the architecture containing the model.

entity top is
generic( limit : INTEGER := 5 );
end top;

architecture top of top is
    procedure disable_cb_ex;
    attribute foreign of disable_cb_ex: procedure is "VHPI test; test_init";
       
signal a,b,c,d : integer := 0;
begin 
    proc1: process 
    begin            
    disable_cb_ex;    
    wait for 1 ps;    a <= 21;
    wait for 1 ps;    b <= 7;
    wait for 1 ps;    c <= 65;
    wait for 1 ps;    c <= 24;
    wait for 1 ps;    a <= 73;
    
    wait for 1 ps;    a <= 1;
    wait for 1 ps;    b <= 1;
    wait for 1 ps;    c <= 32;
    wait for 1 ps;    d <= 12;
    wait for 1 ps;    c <= 643;
    
    wait for 1 ps;    a <= 3;
    wait for 1 ps;    b <= 7;
    wait for 1 ps;    c <= 65;  -- disabling callback on signal c 
    wait for 1 ps;    d <= 124;    
    wait for 1 ps;    a <= 35;  -- disabling callback on signal a    
    wait for 1 ps;    c <= 124;
    wait for 1 ps;    a <= 389;          
    wait for 1 ps;    b <= 62;
    wait;
    end process;    
end architecture top;

vhpi_enable_cb()

Formal Definition

Enables a registered callback. Complete description: IEEE Std 1076™-2008 §23.8

Synopsis

int vhpi_enable_cb (vhpiHandleT cb_obj);

Description

The vhpi_enable_cb() function re-enables a previously disabled callback making the callback function call possible when the event triggering the callback occurs. The cb_obj argument is a handle to the callback to be enabled.

Returned value

The function returns 0 on success and 1 on failure.

Related functions

Use vhpi_disable_cb() to disable the callback.

vhpi_format_value()

Formal Definition

Changes the format used to represent a value.

Complete description: IEEE Std 1076™-2008 §23.9

Synopsis

int vhpi_format_value (vhpiValueT *in_value_p, vhpiValueT *out_value_p);

Description

The in_value_p argument is a pointer to the value structure representing the value which format is to be changed. The out_value_p argument is a pointer to the value structure that specifies the output value format and contains a storage for a newly formatted value. The function converts a value represented by structure referred to by the in_value_p argument to a format specified in the structure referred to by the out_value_p argument.

If a newly formatted value is a scalar, the function writes the newly formatted value to the value member of the output value structure.

If the newly formatted value is represented as an array, string, or using internal representation, you need to allocate memory for the newly formatted value before calling vhpi_format_value and specify the size in bytes and the address of the allocation in the bufSize and value fields of the structure pointed by the out_value_p argument. The newly formatted value is written to the memory location specified with the value field.

If the newly formatted value is represented as an array, string, or using internal representation and the value of the value field of the structure pointed by the out_value_p argument is NULL, the function does not write the value, but returns the minimum number of bytes needed to store a value written in the new format.

If the newly formatted value is represented as a time or physical value or an array of such values, you have to specify the position number of a scale factor into the unit field of the structure pointed by the out_value_p argument, before calling vhpi_format_value.

Returned value

  • The function returns 0:

    If the newly formatted value is a scalar and the operation completes without error.

  • The function returns the minimum size in bytes of storage required to represent the value in the specified format:

    If the newly formatted value is represented as an array, string, or using internal representation and either the value member of the output value structure is NULL or the size provided in the bufSize field of the output value structure is insufficient.

  • In other cases, the function returns a negative integer.

Related functions

vhpi_get_value, vhpi_schedule_transaction.

Example

In the example below, a value of the VHDL real type is read with the vhpi_get_value() function and then converted to the longint type with the vhpi_format_value() function.

vhpiHandleT hdl = vhpi_handle_by_name("top.val_real", NULL);
vhpiValueT value, newValue;
vhpiValueT *valuep, *newValuep;
valuep = &value;
newValuep = &newValue;

value.format = vhpiRealVal;
vhpi_get_value(hdl, valuep);  
newValue.format = vhpiLongIntVal;
vhpi_format_value(valuep, newValuep);

vhpi_get()

Formal Definition

Gets the value of an integer or Boolean property of an object.

Complete description: IEEE Std 1076™-2008 §23.10

Synopsis

vhpiIntT vhpi_get(vhpiIntPropertyT property, vhpiHandleT object);

Description

The property argument is an enumeration constant that specifies the integer or boolean property to be checked. The object argument is a handle to an object whose property is to be checked. The function reads the value of the property.

Returned value

The value of the property if property can be read; or vhpiUndefined otherwise.

Related functions

vhpi_get_phys(), vhpi_get_real(), vhpi_get_str().

Example

In the following VHPI model, the vhpi_get function gets the value of the vhpiKindP property of the subsequent parameters of a VHDL procedure.

void call_vhpi1(const struct vhpiCbDataS* cbDatap) 
{
vhpiHandleT procInst, listParam, iterator, paramDecl = NULL;
vhpiValueT* paramVal = NULL;
int iValue;

procInst = cbDatap->obj;
iterator = vhpi_iterator(vhpiParamDecls, procInst);
if (iterator != NULL )
{
  while ((listParam=vhpi_scan(iterator)) != NULL) 
  {  
    switch (vhpi_get(vhpiKindP, listParam)) 
    {
    case vhpiFileParamDeclK:
      vhpi_printf("vhpiFileParamDeclK\n");                    
      //  ...
      break;        
    case vhpiSigParamDeclK:
      vhpi_printf("vhpiSigParamDeclK\n");
      //  ...
      break;        
    case vhpiVarParamDeclK:
      vhpi_printf("vhpiVarParamDeclK\n");        
      //  ...
      break;        
    case vhpiConstParamDeclK:
      vhpi_printf("vhpiConstParamDeclK\n");
      //  ...      
      break;        
    default: vhpi_printf("default\n");
      break;        
    }
  }
}  
}

The VHDL procedure which parameters are to be checked is the same foreign VHDL procedure in which the VHPI model is registered.

procedure pow2(a: in integer; b: out integer; c: out integer; d: in integer) is
begin                
end pow2; 
attribute foreign of pow2: procedure is "VHPI vhpi1;vhpi1_init";

For the procedure declared above, the program will display the following message:

# VHPI: vhpiConstParamDeclK
# VHPI: vhpiVarParamDeclK
# VHPI: vhpiVarParamDeclK
# VHPI: vhpiConstParamDeclK

vhpi_get_cb_info()

Formal Definition

Gets information about a registered callback.

Complete description: IEEE Std 1076™-2008 §23.11

Synopsis

int vhpi_get_cb_info (vhpiHandleT object, vhpiCbDataT *cb_data_p);

Description

The object argument is a handle to an object of the callback class. The cb_data_p argument is a pointer to a callback data structure. The vhpi_get_cb_info() function is used to retrieve information about the callback specified by the object argument. The information is written to the data structure pointed by the cb_data_p argument. The cb_data_p contents is equivalent to contents of the data structure that is passed as an argument to the vhpi_register_cb function during the callback registration.

The values of the reason, cb_rtb and user_data fields are identical in the cb_data_p structure and the structure passed to the vhpi_register_cb function during the registration.

If the registration callback data structure contains a handle to an object in the obj field, the structure written by vhpi_get_cb_info contains a handle that refers to the same object, otherwise, the value of the obj field is not specified.

If the registration callback data structure include pointers to value and time structures in the value and time fields, respectively, the values of these fields in the resulting cb_data_p structure are pointers to value and time structures containing the same values as the structures which were pointed during the callback registration; otherwise, the time and value fields in the callback data structure written by vhpi_get_cb_info() are NULL.

Returned value

0 on success, 1 on failure.

Related functions

Use vhpi_register_cb() to register a callback.

vhpi_get_foreignf_info()

Formal Definition

Registers a foreign model or application.

Complete description: IEEE Std 1076™-2008 §23.13

Synopsis

int vhpi_get_foreignf_info (vhpiHandleT hdl, vhpiForeignDataT *foreignDatap);

Description

The hdl argument is a handle to an object of class foreignf that represents a foreign model or application whose properties are to be read.

The foreignDatap argument is a pointer to a foreign data structure where the collected information is to be stored. The foreign data structure contains information whether a foreign model is a procedure, function, architecture or an application. The structure also contains the information about the library name where model is stored and the name of the model that is used to locate it in the shared library.

Returned value

0 if the operation completes without error, or 1 otherwise.

Related functions

vhpi_register_foreignf(), vhpi_get_cb_info()

Example

This VHPI program displays the information about all the foreign models registered in the program.

PLI_VOID proc(const struct vhpiCbDataS* cb) {
char *name;  
vhpi_printf("\n");
vhpiForeignDataT foreignData;
vhpiHandleT fmHandle, iterator = NULL;
iterator = vhpi_iterator( vhpiForeignfs, NULL );
if(iterator) {
while ( (fmHandle = vhpi_scan(iterator)) != NULL ) {
    if( vhpi_get_foreign_info( fmHandle, &foreignData ) )
        vhpi_assert(vhpiError, "vhpi_get_foreignf_info(): can't get foreignf info\n");
    else {           
      switch (foreignData.kind)
      {
      case 1:  name = "vhpiArchF";  break;
      case 2:  name = "vhpiFuncF";  break;   
      case 3:  name = "vhpiProcF";  break;
      case 4:  name = "vhpiLibF";  break;   
      case 5:  name = "vhpiAppF";  break;            
      }          
      vhpi_printf( "vhpi_get_foreignf_info(): kind=%s ", name);
      vhpi_printf( "libName=%s ", foreignData.libraryName);
      vhpi_printf( "modName=%s \n", foreignData.modelName);                                           
        }
    }
}  
}

vhpi_get_next_time()

Formal Definition

Gets the time of the next simulation cycle.

Complete description: IEEE Std 1076™-2008 §23.14

Synopsis

int vhpi_get_next_time (vhpiTimeT *time_p);

Description

The time_p argument is a pointer to a time structure in which the next simulation cycle time is to be written. The time structure should be allocated before the vhpi_get_next_time() function call.

Returned value

  • vhpiNoActivity if the next simulation cycle time value is TIME'HIGH and there are no active drivers, or process resumptions, and the following callbacks: vhpiCbAfterDelay, vhpiCbRepAfterDelay, vhpiCbTimeOut, or vhpiCbRepTimeOut are not to occur in the next simulation time.

  • A non-zero value different than vhpiNoActivity if an error occurred.

  • 0 in other cases.

Example

The program scans through all component instances in the project in search for the clk signal and sets the callback that registres the events on that signal.

hdl_iter = vhpi_iterator(vhpiCompInstStmts, vhpi_handle(vhpiRootInst, NULL));
hdl_scan = vhpi_scan(hdl_iter);
hdl = vhpi_handle_by_name("clk", vhpi_scan(hdl_iter));

value.format = vhpiIntVal;
cbData.reason = vhpiCbValueChange;
cbData.cb_rtn = callback_for_signal;
cbData.value = &value;
cbData.time = &time;
cbData.obj = hdl;

vhpi_register_cb(&cbData, vhpiReturnCb);

The callback routine displays the actual time and the time in the next simulation cycle. If the simulation is about to finish or an error occurs, the proper message is displayed.

vhpi_get_time(&time, NULL);
  vhpi_printf("Current simulation time = %d %d\n", time.high, time.low);    
  switch (vhpi_get_next_time(&time))
  {
    case vhpiNoActivity: 
      vhpi_printf("Simulation is over, %d %d\n");
      break;
    case 0:
      vhpi_printf("Next simulation time = %d %d\n", time.high, time.low);
      break;
    default:
      vhpi_check_error(&err_inf);
      break;
  }
  return;
}

vhpi_get_phys()

Formal Definition

Gets the value of a physical property of an object.

Complete description: IEEE Std 1076™-2008 §23.15

Synopsis

vhpiPhysT vhpi_get_phys (vhpiPhysPropertyT property, vhpiHandleT object);

Description

The property argument is an enumeration constant that specifies a physical property to be checked. The object argument is a handle to an object that has the corresponding physical property. The function reads the value of the property.

Returned value

The value of the property if property can be read; or an unspecified value otherwise.

Related functions

vhpi_get, vhpi_get_str, vhpi_get_real.

Example

In the following VHPI program, the vhpi_get_phys function gets the physical properties of the units specified in the declaration of a VHDL physical type.

void describe_type (vhpiHandleT hdlTypeDecl) {
vhpiHandleT hdlUnitDeclIter, hdlUnitDecl, hdlPhysLiteral;
vhpiPhysT phys_pos, phys_val;
__int64 pos, val;
  
hdlUnitDeclIter = vhpi_iterator(vhpiUnitDecls, hdlTypeDecl);
while ( hdlUnitDecl = vhpi_scan (hdlUnitDeclIter) ) {
  if (vhpi_get (vhpiKindP, hdlUnitDecl) == vhpiUnitDeclK) {
    phys_pos = vhpi_get_phys(vhpiPhysPositionP, hdlUnitDecl);
    pos = (__int64)((((__int64)phys_pos.high) << 32) + (__int64)phys_pos.low);

    hdlPhysLiteral = vhpi_handle(vhpiPhysLiteral, hdlUnitDecl);
    if (vhpi_get(vhpiKindP, hdlPhysLiteral) == vhpiPhysLiteralK) {
      phys_pos = vhpi_get_phys (vhpiPhysPositionP, hdlPhysLiteral);
      phys_val = vhpi_get_phys (vhpiPhysValP, hdlPhysLiteral);
      pos = (__int64)((((__int64)phys_pos.high) << 32) + (__int64)phys_pos.low);
      val = (__int64)((((__int64)phys_val.high) << 32) + (__int64)phys_val.low);
      vhpi_printf("PhysPosition: %I64d, PhysVal: %I64d\n", pos, val);
    }
    else vhpi_printf("PhysPosition: %I64d, PhysVal: 1\n", pos, val);
  }
}
}

The vhpiPhysPositionP property contains the values of subsequent units in the type definition expressed in the primary units (in the first unit declared in the physical type definition). The vhpiPhysValP property contains the values of subsequent units expressed in the unit defined in the previous line of the definition. For the type defined below:

type DURATION is range -1E9 to 1E9
units
  fs; -- femtosecond
  ps = 1000 fs; -- picosecond
  ns = 1000 ps; -- nanosecond
  us = 1000 ns; -- microsecond
  ms = 1000 us; -- millisecond
  sec = 1000 ms; -- second
  min = 60 sec; -- minute
end units;

The result will be as follows:

# VHPI: PhysPosition: 1, PhysVal: 1
# VHPI: PhysPosition: 1000, PhysVal: 1000
# VHPI: PhysPosition: 1000000, PhysVal: 1000
# VHPI: PhysPosition: 1000000000, PhysVal: 1000
# VHPI: PhysPosition: 1000000000000, PhysVal: 1000
# VHPI: PhysPosition: 1000000000000000, PhysVal: 1000
# VHPI: PhysPosition: 60000000000000000, PhysVal: 60

vhpi_get_real()

Formal Definition

Gets the value of a real property of an object.

Complete description: IEEE Std 1076™-2008 §23.16

Synopsis

vhpiRealT vhpi_get_real (vhpiRealPropertyT property, vhpiHandleT object);

Description

The property argument is an enumeration constant that specifies a real property to be checked. The object argument is a handle to an object that has the corresponding property. The function reads the value of the property.

Returned value

The value of the property if property can be read; or an unspecified value otherwise.

Related functions

vhpi_get, vhpi_get_str, vhpi_get_phys.

Example

In the following example, the vhpi_get_real function reads the value of the driver that drives the val_real signal.

PLI_VOID get_real ( const struct vhpiCbDataS* cb_p ) {
vhpiRealT value; 
vhpiHandleT hdl, driverHdl, it;
driverHdl = vhpi_handle_by_name("top.val_real", NULL);
it=vhpi_iterator(vhpiDrivers, driverHdl);  
strcpy(name, vhpi_get_str(vhpiNameP, driverHdl));
while (hdl=vhpi_scan(it)) {
  value = vhpi_get_real(vhpiRealValP,hdl);
  vhpi_printf("Signal %s is driven with value %f\n", name, value);    
}

Assuming the program is registered as the foreign procedure get_real that is called in the VHDL process in which the driver is used,

signal val_real  : real;
begin
    proc1: process 
    begin  
    val_real <= 312.8;
    wait for 1 ps;
    get_real;
        wait;
    end process;    
end architecture top;

the message displayed by the program will be as follows:

# VHPI: Signal val_real is driven with value 312.800000 

vhpi_get_str()

Formal Definition

Gets the value of a string property of an object.

Complete description: IEEE Std 1076™-2008 §23.17

Synopsis

const vhpiCharT * vhpi_get_str (vhpiStrPropertyT property, vhpiHandleT object);

Description

The property argument is an enumeration constant that specifies a string property to be checked. The object argument is a handle to an object that has the specified property. The function reads the value of the property.

Returned value

The pointer to the string that is the value of the property if the property can be read, or NULL otherwise.

Related functions

vhpi_get, vhpi_get_phys, vhpi_get_real.

Example

In the following example, the vhpi_get_str function is used to read the definition name of the region one level upper in the hierarchy than the region to which the hdn handle refers.

PLI_VOID vhpi_get_str_ex ( const struct vhpiCbDataS* cb_p ) {
vhpiHandleT ScopeHdl, upScopeHdl;
ScopeHdl = vhpi_handle_by_name(":top.I1.S1", NULL);
upScopeHdl = vhpi_handle(vhpiUpperRegion, ScopeHdl);
string str (vhpi_get_str(vhpiDefNameP, upScopeHdl));
vhpi_printf("Upper region is: %s\n", str.c_str());
}

vhpi_get_time()

Formal Definition

Gets the current simulation time.

Complete description: IEEE Std 1076™-2008 §23.18

Synopsis

void vhpi_get_time (vhpiTimeT *time_p, long *cycles);

Description

The time_p argument is a pointer to a time structure that is a location to which the current simulation time is to be written or NULL. The cycles argument is a pointer to the variable of the long type to which the number of delta cycles is to be written or NULL. Before calling the vhpi_get_time function, the memory for the time structure and the number of delta cycles has to be allocated.

If the time_p argument is a non NULL value and the cycles argument is NULL, the function writes the current simulation time to the time structure. If the time_p and cycles arguments are both not NULL, the function writes the current simulation time to the time structure and the number of delta cycles that have occurred at the current simulation time to the location pointed by the cycles argument.

It is an error if the time_p and cycles arguments are both NULL.

Returned value

void

Related functions

vhpi_get_next_time

Example

In the example below, the function vhpi_get_time returns the current simulation time and the number of cycles that occurred at the current simulation time.

vhpiTimeT *time_str;
time_str  =  (vhpiTimeT*) malloc ( sizeof(vhpiTimeT) );          
long cycle;
long *cyclep = &cycle;  
vhpi_get_time(time_str, cyclep);
vhpi_printf("Current simulation time:\n");
vhpi_printf("time = %d %d\n", time_str->high, time_str->low);  
vhpi_printf("cycles = %d \n", *cyclep);

vhpi_get_value()

Formal Definition

Gets the formatted value of an object that has a value.

Complete description: IEEE Std 1076™-2008 §23.19

Synopsis

int vhpi_get_value (vhpiHandleT expr, vhpiValueT *value_p);

Description

The expr argument is a handle to an object to get the value from. The value_p argument is a pointer to the value structure vhpiValueT which is a destination for the value that is read. The value structure also specifies the format in which a value is to be written. For the full description of the vhpiValueT structure refer to the §22.2.8 section in the IEEE Std 1076-2008™.

The function reads a value from the object referred to by the expr handle. The data representation is specified by the format field of the value structure referred to by the value_p argument. If the formatted value is a scalar, the function writes the value to the value field of the value structure.

If the formatted value is represented as an array, string, or using internal representation, the VHPI program allocates the storage for the formatted value and writes the size of allocated memory into the bufSize field and the address of storage into the value field. In that case, the function writes the formatted value to the memory location specified with the value field.

If the formatted value is represented as an array, string, or using internal representation and the value of the value field of the value structure is NULL, the function, instead of writing a formatted value, returns the minimum number of bytes of the storage that would be required to write a value.

If the format specified in the format field is vhpiObjTypeVal, the representation of the value depends on the type of the object referred to by the expr argument. The function writes to the vhpiFormatT field of the structure a native VHPI format corresponding to VHDL format of the object referred to by expr argument.

The table specifying the native VHPI types and the corresponding VHDL types can be found in the clause §22.4 of the IEEE Std 1076-2008™.

If the formatted value is represented as a time or physical value, or as an array of such values, the function writes the position number of a scale factor to the unit member of the data structure. If the object is a time or physical literal, the scale factor is the position number of the unit of the literal; otherwise, the scale factor is 1.

Returned value

Function returns 0:

  • If the formatted value is a scalar and the operation completes without error.

  • If the formatted value is represented as an array, string, or using internal representation, the value member of the value structure is not NULL, the size provided in the bufSize member of the value structure is sufficient and the operation completes without error.

Function returns the minimum size in bytes of storage required to represent the value in the specified format:

  • If the formatted value is represented as an array, string, or using internal representation and either the value member of the value structure is NULL or the size provided in the bufSize member of the value structure is insufficient.

In other cases, a negative integer is returned.

Example

In the below example, the vhpi_get_value function gets the value of the bit_var1 variable referred to by the hnd handle. The value is written to the value structure. Before the vhpi_get_value call, the memory for the value structure is allocated with the malloc function. The format field is set to vhpiIntVal to correspond to the type of the variable which value is to be read.

PLI_VOID get_val_ex ( const struct vhpiCbDataS* cb_p ) {
  vhpiHandleT hnd  = vhpi_handle_by_name("top.proc1.var1", NULL);  
  vhpiValueT *value;
  value = (vhpiValueT*) malloc(sizeof(vhpiValueT));
  value->format = vhpiIntVal;
  value->bufSize = 0;
  value->value.intg = 0;  
  vhpi_get_value(hnd, value);
  vhpi_printf( "value is %d\n", value->value.intg );
}

vhpi_handle()

Formal Definition

Releases a handle.

Complete description: IEEE Std 1076™-2008 §23.20

Synopsis

vhpiHandleT vhpi_handle (vhpiOneToOneT type, vhpiHandleT referenceHandle);

Description

The type argument is an enumeration value that corresponds to a one-to-one association role. The referenceHandle argument is a handle to a reference object, that is, an object of the class that is the reference class of the one-to-one association.

If the association corresponding to the value of the type argument has a multiplicity of 1, or if the association has a multiplicity of 0..1 and a target object is associated with the reference object, the function returns a handle to the target object of the association. If the association has a multiplicity of 0..1 and no object is associated with the reference object, the function returns NULL.

Returned value

A handle to the target object if one exists, or NULL otherwise.

Example

In the following example, the call to the vhpi_handle function is used to get the handles to the region in which the signal referred to by the sigHdl handle is declared, the region one level upper in the hierarchy to that region, and to the architectures of these regions.

PLI_VOID sig_decl_region ( vhpiHandleT sigHdl) {
vhpiHandleT currentHdl, upperHdl, archHdl;

  currentHdl = vhpi_handle ( vhpiImmRegion, sigHdl );  
  upperHdl = vhpi_handle(vhpiUpperRegion, currentHdl);  
  if (vhpi_get(vhpiKindP, currentHdl) == vhpiCompInstStmtK) {
  archHdl = vhpi_handle(vhpiDesignUnit, currentHdl);
  vhpi_printf ( "signal: %s\n", vhpi_get_str(vhpiNameP, sigHdl));
  vhpi_printf ( "region: %s\n", vhpi_get_str(vhpiFullNameP, currentHdl));  
  vhpi_printf ( "current architecture: %s\n", vhpi_get_str(vhpiNameP, archHdl));  
  }  
  if (vhpi_get(vhpiKindP, upperHdl) == vhpiCompInstStmtK) {
  archHdl = vhpi_handle(vhpiDesignUnit, upperHdl);
  vhpi_printf ( "region: %s\n", vhpi_get_str(vhpiFullNameP, upperHdl));  
  vhpi_printf ( "parent architecture: %s\n", vhpi_get_str ( vhpiNameP, archHdl));
  }
}

vhpi_handle_by_index()

Formal Definition

Gets a handle to an object that is a target of an ordered one-to-many association.

Complete description: IEEE Std 1076™-2008 §23.21

Synopsis

vhpiHandleT vhpi_handle_by_index (vhpiOneToManyT itRel, vhpiHandleT parent, int32_t indx);

Description

The itRel argument is an enumeration value that corresponds to an ordered one-to-many association role. The parent argument is a handle to a reference object, that is, an object of the class that is the reference class of the one-to-many association. The indx argument is the index of a target object in the one-to-many association.

The function returns a handle to the target object which position corresponds to the value specified with the indx argument. If a value specified with the indx argument is greater than number of target objects in the one-to-many association, the function returns NULL.

Returned value

A handle to a located object, if any, or NULL otherwise.

Related functions

Use the vhpi_iterator() and vhpi_scan() functions to get each element of the parent handle.

Example

In the below example, the function vhpi_handle_by_index is used to get an access to each element of a 4-bit vector referred to by the hnd_byNym handle.

for (int idx=0; idx<4; idx++) {    
hndByIdx =   vhpi_handle_by_index( vhpiIndexedNames, hnd_byNym, idx );
vhpi_printf("Signal name: %s\n", vhpi_get_str(vhpiNameP, hndByIdx));
vhpi_get_value(hndByIdx, valueByIdx);
vhpi_printf( "Signal value: %d\n", valueByIdx->value.intg );    
}

vhpi_handle_by_name()

Formal Definition

Gets a handle to an object that is identified by its name.

Complete description: IEEE Std 1076™-2008 §23.22

Synopsis

vhpiHandleT vhpi_handle_by_name (const char *name, vhpiHandleT scope);

Description

The name argument is a pointer to a string to be searched. The scope argument represents either a region in the design hierarchy or a scope in a library to search in.

In the first case, the scope argument is a handle to an object of the class region, in the latter, a handle to an object of the class LexicalScope. If the scope argument is NULL, the vhpi_handle_by_name() function searches the matching string in the entire library or entire design hierarchy.

The design hierarchy string and library search string can be specified either in the absolute or in the relative form. The absolute design hierarchy search string has a form as follows:

@ library_name_property : package_name_property :[ shared_variable_name_property: ] [ named_entity_name_property ]

The absolute library search string form is shown below:

@ unit_name_property { . lexical_scope_ name_property } [ . named_entity_ name_property]

When the search string is specified in the relative form, the hierarchical name of an object is a concatenation of the design hierarchy (or the library scope) specified with the scope argument and the relative search string.

Returned value

A handle to a located object, if any, or NULL otherwise.

Related functions

Use vhpi_get_str() to get the name (vhpiNameP) or full name (vhpiFullNameP) of an object.

Example

//absolute design hierarchy search string
vhpiHandleT hnd0  =  vhpi_handle_by_name("top.i2.proc_and.var2", NULL);  
//specifies the i1 signal from the top level hierarchy region. 
vhpiHandleT hnd1  =  vhpi_handle_by_name("i1", NULL);      
//specifies the proc_and signal from the region reffered to by hnd1
vhpiHandleT hnd2  =  vhpi_handle_by_name("proc_and", hnd1);

vhpi_is_printable()

Formal Definition

Determines whether a given character is a graphic character.

Complete description: IEEE Std 1076™-2008 §23.23

Synopsis

int vhpi_is_printable( char ch );

Description

The function checks whether a character specified with the ch argument is a graphic character.

Returned value

Returns 1 if the specified value is a graphic character, or 0 otherwise.

Related functions

vhpi_is_printf.

Example

The below VHPI program, writes the strings stored in the str array to the VHDL array referred to by the hnd_p handle. Before writing, the program checks with the vhpi_is_printable function whether any of the strings to be written contain non-printable characters. If so, the program displays an appropriate warning message with the vhpi_assert function and continue checking subsequent strings.

vhpiHandleT iter = vhpi_iterator(vhpiIndexedNames, hnd_p);      
for (int idy=0; idy<SIZE; idy++) {
strcp = str[idy];
 for (int idx=0; idx<MAX; idx++) {        
  if (vhpi_is_printable(*str[idy]) == 0) {
    vhpi_assert(vhpiWarning, "Name '%s' contains non-printable signs\n",strcp);    
    break;
    }
  else
    if (idx == MAX-1) {
    value_p->value.str   = strcp;
    hdl = vhpi_scan(iter);    
    vhpi_put_value(hdl, value_p, vhpiDeposit);      
    }
  str[idy]++;    
 }
}

vhpi_iterator()

Formal Definition

Creates an iterator for a one-to-many association.

Complete description: IEEE Std 1076™-2008 §23.24

Synopsis

vhpiHandleT vhpi_iterator (vhpiOneToManyT type, vhpiHandleT referenceHandle);

Description

The type argument is an enumeration value that corresponds to a one-to-many association role. The referenceHandle argument is a handle to a reference object, that is, to an object of the class that is the reference class of the one-to-many association.

If a one-to-many association has at least one target object, the function creates a new object of the iterator class, initializes the iterator set of the objects to be the set of target objects in the one-to-many association, initializes the position of the iterator object to point to the first element in the object set. If the association has no objects, NULL is returned.

If the one-to-many association is ordered, the elements in the iterator set have the same order as the target objects of the one-to-many association. Otherwise, the order of elements is not specified by IEEE Std 1076-2008.

Returned value

A handle to the object of class iterator, if such an object is created, or NULL otherwise.

Related functions

Use vhpi_scan() to get each element of the iteration.

Example

In the below VHPI program, the vhpi_iterator and the vhpi_scan functions are used to iterate through the parameters of the VHDL procedure. The procedure whose parameters are scanned is the same procedure in which the VHPI model is registered. The program sets the handles to each parameter of the procedure and reads their values with the vhpi_get_value function.

void proc1(const struct vhpiCbDataS* cb)
{
vhpiValueT *value;
value = (vhpiValueT*) malloc ( sizeof(vhpiValueT) );    
value->bufSize = 0;
value->value.real = 0;    

value->format = vhpiRealVal;  
vhpiHandleT hScope = cb->obj;
vhpiHandleT hIter = vhpi_iterator( vhpiParamDecls, hScope );
vhpiHandleT hParam;    
while (hParam = vhpi_scan( hIter )) 
{
  vhpi_get_value(hParam, value);    
  vhpi_printf("%s value is %f\n", vhpi_get_str(vhpiNameP, hParam), value->value.real);
}    
vhpi_printf("\n");  
}

Assuming that the VHPI model is registered as the proc_vhpi procedure, the following VHDL code will display the values of the proc_vhpi procedure parameters when any of the parameters change.

process 
begin           
  wait for 1ps;  
  proc_vhpi(value1, value, value2);  
  wait for 1ps;           
  value <= value  + 0.972;    
  value1 <= value1 + 1.410;
  value2 <= value2 - 1.569;
end process;

vhpi_printf()

Formal Definition

Writes a message to the console.

Complete description: IEEE Std 1076™-2008 §23.25

Synopsis

int vhpi_printf (const char *format, ...);

Description

The format argument is a pointer to a format string that may contain conversion codes as defined for the C printf function in the standard ISO/IEC 9899:1999/Cor 1:2001. The format argument and subsequent arguments are interpreted as it is specified for the C printf function in ISO/IEC 9899:1999/Cor 1:2001 to form a formatted character string that is written to the console.

Note that you can redirect the contents of the console window with the transcript file command. Use the -msgtype argument with the vphi parameter, as shown below, to redirect only vhpi-related commands.

transcript file -msgtype vhpi -append <filename>

Returned value

The number of characters written to the console, or -1 if an error occurred.

Example

The below example prints the value of the signal referred to by the handle hnd.

vhpiHandleT hnd  = vhpi_handle_by_name("top.sig1", NULL);  
vhpiValueT *value;
value = (vhpiValueT*) malloc ( sizeof(vhpiValueT) );
value->format  = vhpiIntVal;
value->bufSize = 0;
value->value.intg = 0;  
vhpi_get_value(hnd, value);
vhpi_printf( "signal value: %d\n", value->value.intg );

vhpi_put_value()

Formal Definition

Updates the value of an object or provides the return value of a foreign function call.

Complete description: IEEE Std 1076™-2008 §23.28

Synopsis

int vhpi_put_value (vhpiHandleT object, vhpiValueT *value_p, vhpiPutValueModeT mode);

Description

The vhpi_put_value() function updates the value of an object or provides the return value of a foreign function call. The object argument is a handle to an object which value is to be changed. The object can be of the class objDecl, name, driver, or a handle to an object of the class funcCall for which the associated subpBody object has the value vhpiTrue for the IsForeign property.

The value_p argument is a handle to a value structure that specifies a value which is to be assigned, or the return value of a foreign function call.

The mode argument is an enumeration constant that specifies how the update is to be performed. Refer to IEEE Std 1076™-2008 §22.5 for more information.

Returned value

0 if the operation completes without error, or a non-zero value otherwise.

Related functions

vhpi_get_value, vhpi_schedule_transaction.

Example

The program puts a value to the variable var1 referred to by the handle hnd_p.

vhpiHandleT hnd_p  =  vhpi_handle_by_name("top.proc1.var1", NULL);  
vhpiValueT *value_p;  
vhpiPutValueModeT put_mode;  
value_p = (vhpiValueT*) malloc ( sizeof(vhpiValueT) );  

value_p->format  = vhpiIntVal;
value_p->bufSize  = 0;
value_p->value.intg  = 456;
vhpi_put_value(hnd_p, value_p, vhpiDeposit);

vhpi_register_cb()

Formal Definition

Registers a callback.

Complete description: IEEE Std 1076™-2008 §23.29

Synopsis

vhpiHandleT vhpi_register_cb (vhpiCbDataT *cb_data_p, int32_t flags);

Description

The vhpi_register_cb() function registers a callback for a specific reason. The condition of occurrence of the callback is specified with the cb_data_p argument. The argument is of the vhpiCbDataT structure type that contains the information about the way the callback is to be registered.

There are two callback flags defined: vhpiReturnCb and vhpiDisableCb. A call to the function is said to set a flag if the bit in the position denoting the flag is set to 1. If the bit in that position is set to 0, the call is said to clear the callback flag.

If the vhpiReturnCb flag is set, the function returns a handle to an object of class callback that represents the registered callback. If a call to the function clears the vhpiReturnCb flag, the function returns NULL. If a call to the function sets the vhpiDisableCb flag, the function sets the registered callback to the disabled state. If a call to the function clears the vhpiDisableCb flag, the function sets the registered callback to the enabled state.

Returned value

A handle to the registered callback, or NULL.

Related functions

Use vhpi_remove_cb() to remove the callback. Use vhpi_get_cb_info() to get information about the given callback.

Example

In the following example, the vhpi_register_cb function is used to register callbacks on the all elements of the VHDL array shown below:

type MEM    is array  (NATURAL range <>) of BIT_VECTOR (7 downto  0);
signal sig_vec : MEM(3 downto 0);

The handles reffering to each bit_vector element in the array are aquired with the vhpi_scan and vhpi_iterate functions. The vhpi_register_cb function is placed in the while loop to register callbacks for all elements of the array.

vhpiHandleT hnd       = vhpi_handle_by_name("top.sig_vec", NULL);
            
vhpiCbDataT *cbDataAction;
vhpiValueT  *Value;
vhpiTimeT  *Time;
cbDataAction = (vhpiCbDataT*) malloc ( sizeof(vhpiCbDataT) );
Value = (vhpiValueT*) malloc ( sizeof(vhpiValueT) );
Time  = (vhpiTimeT*)  malloc ( sizeof(vhpiTimeT) );

Value->format = vhpiStrVal;
Value->bufSize = 0;
Value->value.intgs = 0;
cbDataAction->cb_rtn = ValueChangeEvent;
cbDataAction->reason = vhpiCbValueChange; 
cbDataAction->time = Time;                
cbDataAction->value = Value;
cbDataAction->user_data = NULL;
  
vhpiHandleT hnditr = vhpi_iterator(vhpiIndexedNames, hnd);   
while ( vhpiHandleT hndByIdx = vhpi_scan (hnditr) ) {
    cbDataAction->obj = hndByIdx;      
    vhpi_register_cb (cbDataAction, vhpiReturnCb);
}

vhpi_register_foreignf()

Formal Definition

Registers a foreign model or application.

Complete description: IEEE Std 1076™-2008 §23.30

Synopsis

vhpiHandleT vhpi_register_foreignf (vhpiForeignDataT *foreignDatap);

Description

The foreignDatap argument is a pointer to a foreign data structure. The vhpi_register_foreignf() function registers the foreign model or application according to the information specified in the foreign data structure.

The foreign data structure is described in the Building VHPI Applications section.

Returned value

A handle to an object of the foreignf class that represents the foreign model or application, if the operation completes without error; or NULL otherwise.

Example

The example below shows how to register C functions as VHPI models. The arch, proc and func are the functions that will be registered as a VHDL architecture, process and function, respectively. For brevity, the function bodies are skipped.

The foreignDataArray[] array stores the vhpiForeignDataT structures specifying the parameters for each function registration. The first field of the vhpiForeignDataT structure specifies which VHDL statement will be represented by the VHDL model. The second and the third fields specifies the name of the shared library containing VHPI models and the names of the models in the library, respectively.

PLI_VOID arch(const struct vhpiCbDataS* cb) { /* ... */}  
PLI_VOID proc(const struct vhpiCbDataS* cb) { /* ... */}  
PLI_VOID func(const struct vhpiCbDataS* cb) {
vhpiValueT *ret_value;
vhpiHandleT func;
  // ...  
    ret_value = (vhpiValueT*) malloc(sizeof(vhpiValueT));
    ret_value->format = vhpiEnumVal;
  ret_value->value.enumv = 1;
  vhpi_put_value(cb->obj, ret_value, vhpiDeposit);
}

PLI_VOID  startup_1()
{
  vhpiForeignDataT foreignDataArray[] = 
  {                                 
    { vhpiArchF, "vhpi_lib", "arch_dec", arch, NULL},      
    { vhpiProcF, "vhpi_lib", "proc_dec", NULL, proc},
    { vhpiFuncF, "vhpi_lib", "func_dec", NULL, func},        
  };  

  for (int i=0; i<3; i++)  
    vhpi_register_foreignf(&(foreignDataArray[i]));
}  

PLI_VOID (*vhpi_startup_routines[])() = { startup_1 , 0L };

The first array element contains the vhpiForeignDataT structure associated with the foreign architecture registration, so the first structure field is set to vhpiArchF. The arch function is registered on the elaboration phase, thus fourth field is set to the function name (arch) and the fifth field is set to NULL. The proc and func functions are registered as a VHDL process and function, so in the structures relating to them the first field is set to vhpiProcF and vhpiFuncF, respectively. Both functions are registered on the runtime phase, therefore the fourth field is set to NULL and the function names are in the fifth field.

At the end of the code, the functions are registered with the vhpi_register_foreignf function called from the for loop.

The models are registered in the VHDL code as it is shown below:

entity ex is end;
architecture foreign_arch of ex is
  attribute foreign of foreign_arch : architecture is "VHPI lib_name; arch_dec";
begin
end;

entity tb is
end entity tb;

architecture arch of tb is  
procedure proc;
attribute foreign of proc : procedure is "VHPI vhpi_lib; proc_dec";

function func (signal a: BOOLEAN) return BOOLEAN is
begin
end func; 
attribute FOREIGN of func: function is "VHPI vhpi_lib; func_dec";

vhpi_release_handle()

Formal Definition

Releases a handle.

Complete description: IEEE Std 1076™-2008 §23.31

Synopsis

int vhpi_release_handle (vhpiHandleT object);

Description

The object argument is a handle that refers to an object. The function releases the handle.

Returned value

The function returns 0 on success and 1 on failure.

Example

The following program releases the handles to signals which values are equal to the value of the crd variable.

vhpiHandleT hnd_i = vhpi_iterator(vhpiSigDecls, hnd_s);
vhpiHandleT hnd_r = hnd_s;  
while (hnd_r = vhpi_scan(hnd_i)) {
  vhpi_get_value(hnd_r, value);
  if (value->value.intg == crd) {
  vhpi_printf( "handle reffering to %s released, %d\n",vhpi_get_str(vhpiFullNameP, hnd_r), value->value.intg );    
  vhpi_release_handle(hnd_r);        
  }  
}

vhpi_remove_cb()

Formal Definition

Removes a previously registered callback.

Complete description: IEEE Std 1076™-2008 §23.32

Synopsis

int vhpi_remove_cb (vhpiHandleT cb_obj);

Description

The vhpi_remove_cb() is used to remove a callback that was registered using the vhpi_register_cb() function. The function argument should be a handle to the callback. The function returns 0 on success and 1 on failure. After the callback has been removed, the callback handle becomes invalid (the interface implicitly frees the memory that was allocated for the callback including the callback handle).

Returned value

0 on success, 1 on failure.

Related functions

Use vhpi_register_cb() to register a callback.

vhpi_scan()

Formal Definition

Gets a handle to an object that is pointed by an iterator and advances the iterator.

Complete description: IEEE Std 1076™-2008 §23.33

Synopsis

vhpiHandleT vhpi_scan (vhpiHandleT iterator);

Description

The iterator argument is a handle to an object of the class iterator. The function returns a handle to an element pointed by the iterator position and updates its position to point the next element in the iterator set, if the next element exists, or to no object otherwise. If the iterator position does not point to any element, vhpi_scan() returns NULL.

Returned value

A handle to an object on which the iterator is set, or NULL.

Related functions

Use vhpi_iterator() to get an iterator handle.

Example

The example displays all the signals from the design region specified with the hnd_s handle. The vhpi_scan and vhpi_iterator functions are used to scan over the specified hierarchy to get the handles to the signal declarations. The handles are passed to the vhpi_get_value and vhpi_get_str functions to obtain the signal names and the current values.

vhpiHandleT hnd_i = vhpi_iterator(vhpiSigDecls, hnd_s);
vhpiHandleT hnd_r = hnd_s;  
while (hnd_r = vhpi_scan(hnd_i)) {
 vhpi_printf("region: %s, signals: %s\n", vhpi_get_str(vhpiNameP, hnd_s), vhpi_get_str(vhpiNameP, hnd_r));
 vhpi_release_handle(hnd_r);
}

vhpi_schedule_transaction()

Formal Definition

Schedules a transaction on a driver or transactions on a collection of drivers.

Complete description: IEEE Std 1076™-2008 §23.34

Synopsis

int vhpi_schedule_transaction (vhpiHandleT drivHdl, vhpiValueT *value_p,
                               uint32_t numValues, vhpiTimeT *delayp,
                               vhpiDelayModeT delayMode, vhpiTimeT *pulseRejp);

Description

The function schedules one or more transaction on one or more drivers specified by drivHdl argument using the value or values specified with the value_p and numValues arguments.

The drivHdl argument is a handle to an object of class driver or driverCollection. The value_p argument is a pointer to a value structure or array of value structures, or NULL. The numValues argument specifies the number of value structures.

The delayp argument is a pointer to a time structure that specifies the relative delay. The delayMode argument is an enumeration constant that allows you to specify which delay mechanism is to be used. If the argument value is vhpiInertial, the internal delay is used. If the value is vhpiTransport, the transport delay is used. The pulseRejp argument is a pointer to a time structure that specifies the pulse rejection limit or NULL.

If the delayMode argument is vhpiInertial and the pulseRejp argument is not NULL, the value of the time structure pointed to by the pulseRejp argument is the pulse rejection limit. The value shall not be greater than the delay. If the delayMode is vhpiInertial and the pulseRejp argument is NULL, the pulse rejection limit is equal to the delay. If the delayMode argument is vhpiTransport, the pulseRejp argument is ignored by the tool.

Returned value

0 if the operation completes without error, or a non-zero value if an error occurs.

Related functions

vhpi_put_value, vhpi_get_value.

Example

In the following example, the function vhpi_schedule_transaction is used to set transactions on the g_hdlDriver driver and associates this driver with a VHDL signal. The values of the driver and times of the values occurrence are passed to the vhpi_schedule_transaction function as parameters in the subsequent vhpi_schedule_transaction function calls.

void set_signal_value ( int value, int time )
{
  vhpiValueT      Values;
  vhpiTimeT      Time;
    
    Values.format = vhpiEnumVal;
    Values.value.enumv = value;
    Time.low = time;
    Time.high = 0;  
    vhpi_schedule_transaction ( g_hdlDriver, &Values, 1, &Time, vhpiTransport, &Time );
}

EXPORT PLI_VOID call_vhpi101_exec ( const struct vhpiCbDataS* cb_p )
{
  set_signal_value ( 1, 000 );
  set_signal_value ( 0, 200 );
  set_signal_value ( 1, 400 );
  set_signal_value ( 1, 550 );
  set_signal_value ( 0, 550 );
  set_signal_value ( 1, 700 );
  set_signal_value ( 0, 800 );
  set_signal_value ( 1, 801 );
  set_signal_value ( 0, 802 );
  set_signal_value ( 1, 900 );    
}

The driver to which the transaction is applied is created using the vhpi_create function in the function call_vhpi101_elabf that will be registered on elaboration as a foreign architecture. The created driver is associated with the top.source signal and with the process statement referred to by the hdlProcess handle which is also created using the vhpi_create function. The process, in turn, is associated with the foreign architecture arch in which this VHPI program will be registered.

EXPORT PLI_VOID call_vhpi101_elabf ( const struct vhpiCbDataS* cb_p )
{
vhpiHandleT hdlForeignfsIter, hdlForeign, hdlProcess, hdlSignal;
hdlForeign = vhpi_handle_by_name ( "arch", NULL );    

hdlProcess = vhpi_create (vhpiProcessStmtK, hdlForeign, NULL);
hdlSignal = vhpi_handle_by_name ( "top:source", NULL );    
g_hdlDriver = vhpi_create (vhpiDriverK, hdlSignal, hdlProcess);
}

The function call_vhpi101_elabf in which the driver and associated process is created, and the function call_vhpi101_exec in which transaction on the driver is set are registered as follows:

EXPORT PLI_VOID startup_1()
{
int i;  
vhpiForeignDataT foreignDataArray[] = {      
  {vhpiArchFK, "vhpi101", "vhpi101_init", call_vhpi101_elabf, call_vhpi101_exec },      
};

The VHPI model is registered as a foreign architecture arch and the foregin_model component of that architecutre is instantiated in the entity top. When the component is instantiated, the process that changes the value of the source signal according to the transaction defined in the VHPI code is created.

attribute foreign of win : architecture is
 "VHPI vhpi101; vhpi101_init";
begin      
end architecture win;

use std.textio.all;
entity top is
end top;  

architecture a of top is
component arch is    
end component arch;                    

file results: text open write_mode is "results.txt";      
signal source : bit;  
begin    
foreign_model: arch;  
write_to_file: process (source)
variable l_out: line;
begin    
 write (l_out, now, right, 15); 
 write (l_out, source, right, 2);
 writeline (results, l_out);
end process;

The process write_to_file writes the values and current simulation time when the source signal changes. The output file is as follows:

   0 ns 0
   0 ns 1
 200 ns 0
 400 ns 1
 550 ns 0
 700 ns 1
 800 ns 0
 801 ns 1
 802 ns 0
 900 ns 1

vhpi_vprintf()

Formal Definition

Writes a message to the console.

Complete description: IEEE Std 1076™-2008 §23.35

Synopsis

int vhpi_vprintf (const char *format, va_list args);

Description

The vhpi_vprintf function writes the formatted string to the console.

The format argument is a pointer to a format string that may contain conversion codes described in ISO/IEC 9899:1999/Cor 1:2001. The args argument is of the type va_list that is used to hold information about variable arguments. The arguments are interpreted in the same way as specified in SO/IEC 9899:1999/Cor 1:2001 for the C vprintf function to form a formatted character string that is written to the console.

Note that you can redirect the contents of the console window with the transcript file command. Use the -msgtype argument with the parameter vphi, as shown below, to redirect only vhpi-related commands.

transcript file -msgtype vhpi -append <filename>

Returned value

The number of characters written to the console, or -1 if an error occurs.

Example

In the below example, the vhpi_vprintf function displays the simulation time and the memory_var signal value. The data is written to the vhpiHandleT and vhpiValueT structures and, along with the signal name, they are passed to the vhpi_print_formatted function from which the vhpi_vprintf function is called.

vhpiValueT *value;
vhpiTimeT *time;
value = (vhpiValueT*) malloc(sizeof(vhpiValueT));
time = (vhpiTimeT*) malloc(sizeof(vhpiTimeT));

vhpiHandleT hnd  = vhpi_handle_by_name("top.signal_1", NULL);  

value->format = vhpiIntVal;
value->bufSize = 0;
value->value.intg = 0;  
vhpi_get_value(hnd, value);
vhpi_get_time(time, NULL);

*vp = time->low;
*tp = value->value.intg;
vhpi_print_formatted( "time %d: value of signal %s is %d\n", t, vhpi_get_str(vhpiNameP, hnd), v);

The vhpi_print_formatted function declaration is shown below. The formatted string is passed as the first function parameter. The signal value, signal name and the current time are treated as a list of the va_list type.

PLI_VOID vhpi_print_formatted (char * format, ...){
 va_list args;
 va_start   (args, format);
 vhpi_vprintf (format, args);
 va_end (args);
}
Ask Us a Question
x

Ask Us a Question

x
Captcha ImageReload Captcha
Incorrect data entered.
Thank you! Your question has been submitted. Please allow 1-3 business days for someone to respond to your question.
Internal error occurred. Your question was not submitted. Please contact us using Feedback form.