« Prev | Next » 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); } Previous article Next article
