VHPI documentation

[Blebowski]

Hi,

I was wondering whether it would be worth it to document what part of VHPI is supported, and what is not.
E.g. as set of "tables" that would contain Handle Kinds on one axis, Property kinds on next axis, and cell entry
background color would indicate support of given combination of property / handle kind. There would be a
table for each of the supported VHPI functions (where it makes sense). I have seen such approach in some
of the commercial simulators.

If I have time, I can have a look at it, but It would be good to know in advance if you would merge such contribution
since its quiet tedious to go through the specification and implementation and figure out the combinations.

[bpadalino]

If you've seen this in some of the commercial simulators, then I'd say it'd probably worthwhile to do.

I can try and help if you want to coordinate what to do and where to look.

Let me know.

[nickg]

I'm OK with it as long as the table is not enormous and if some users find it helpful.
It does sound a bit tedious to produce through. Perhaps an alternative would be to develop tests for the missing properties or improve the coverage of the existing ones.

[Blebowski]

Yeah, it could get quite big, and the work is tedious.
I will try to come-up with something useful.

[metebalci]

I also think it would be a useful document. Would something like this work ? There can be mistakes.

VHPI Support in NVC

Implementation Status Summary

Category	Status	Implementation Level
Handle Management	✅ Complete	Full support
Property Access	✅ Complete	Full support
Value Operations	⚠️ Partial	Limited format and mode support
Callback System	⚠️ Partial	Limited subset supported
Error Handling	✅ Complete	Full support
Time Operations	✅ Complete	Full support
Simulation Control	⚠️ Partial	Stop/Finish only, no Reset
Object Traversal	✅ Complete	Full support
Foreign Models	⚠️ Partial	Functions/procedures only
Advanced Features	❌ Not Implemented	Missing some features

Detailed Function Support

✅ Fully Implemented Functions

Handle Management

• vhpi_handle() - Get handle for one-to-one relationships
• vhpi_handle_by_name() - Get handle by hierarchical name
• vhpi_handle_by_index() - Get handle by index in collection
• vhpi_iterator() - Create iterator for one-to-many relationships
• vhpi_scan() - Scan through iterator
• vhpi_release_handle() - Release handle resources
• vhpi_compare_handles() - Compare two handles

Property Access

• vhpi_get() - Get integer/boolean properties
• vhpi_get_str() - Get string properties
• vhpi_get_real() - Get real number properties
• vhpi_get_phys() - Get physical properties

Value Operations

• vhpi_get_value() - Read object values (limited format support)
• vhpi_put_value() - Write object values (partial mode support - see limitations below)

Callback System

• vhpi_register_cb() - Register callbacks for limited simulation events (see supported callbacks below)
• vhpi_remove_cb() - Remove registered callbacks
• vhpi_disable_cb() / vhpi_enable_cb() - Control callback state
• vhpi_get_cb_info() - Get callback information

Time Operations

• vhpi_get_time() - Get current simulation time
• vhpi_get_next_time() - Get next scheduled event time

Simulation Control

• vhpi_control() - Control simulation (stop, finish only - reset not supported)

Error Handling

• vhpi_check_error() - Check for API errors
• vhpi_assert() - Generate VHPI assertions

Utility Functions

• vhpi_printf() / vhpi_vprintf() - Formatted output
• vhpi_is_printable() - Check if character is printable

Sensitivity Set Operations

• vhpi_sens_zero() - Clear sensitivity bitmap
• vhpi_sens_set() - Set bit in sensitivity bitmap
• vhpi_sens_clr() - Clear bit in sensitivity bitmap
• vhpi_sens_isset() - Check if bit is set
• vhpi_sens_first() - Find first set bit

Foreign Model Registration

• vhpi_register_foreignf() - Register foreign functions/procedures only
• vhpi_get_foreignf_info() - Get foreign model information

❌ Not Implemented Functions

These functions are marked with VHPI_MISSING and will generate a fatal error if called:

• vhpi_protected_call() - Call protected type methods
• vhpi_schedule_transaction() - Schedule signal transactions
• vhpi_format_value() - Format value conversions
• vhpi_create() - Create new VHPI objects
• vhpi_get_data() / vhpi_put_data() - Save/restore foreign model data

Supported Object Classes

NVC supports all standard VHPI object classes as defined in the header file, including:

Design Units

• vhpiEntityDeclK - Entity declarations
• vhpiArchBodyK - Architecture bodies
• vhpiConfigDeclK - Configuration declarations
• vhpiPackDeclK / vhpiPackBodyK - Package declarations/bodies

Declarations

• vhpiSigDeclK - Signal declarations
• vhpiVarDeclK - Variable declarations
• vhpiConstDeclK - Constant declarations
• vhpiGenericDeclK - Generic declarations
• vhpiPortDeclK - Port declarations

Statements

• vhpiProcessStmtK - Process statements
• vhpiBlockStmtK - Block statements
• vhpiCompInstStmtK - Component instantiation statements
• Various assignment and control statements

Types and Expressions

• All type declaration kinds (integer, enumeration, array, record, etc.)
• Expression kinds (literals, operators, function calls, etc.)

Supported Callback Reasons

NVC supports only a limited subset of VHPI callback reasons (17 out of 49 defined in the standard):

✅ Implemented Callback Reasons

Simulation Phase Callbacks

• vhpiCbStartOfSimulation / vhpiCbEndOfSimulation
• vhpiCbStartOfInitialization / vhpiCbEndOfInitialization

Time-based Callbacks

• vhpiCbAfterDelay - One-time delay callback
• vhpiCbNextTimeStep / vhpiCbRepNextTimeStep - Next simulation time step
• vhpiCbStartOfNextCycle / vhpiCbRepStartOfNextCycle - Start of simulation cycle
• vhpiCbEndOfTimeStep / vhpiCbRepEndOfTimeStep - End of simulation time step
• vhpiCbLastKnownDeltaCycle / vhpiCbRepLastKnownDeltaCycle - Last delta cycle

Object Change Callbacks

• vhpiCbValueChange - Signal/variable value changes

Process Callbacks

• vhpiCbStartOfProcesses / vhpiCbRepStartOfProcesses - Start of process execution
• vhpiCbEndOfProcesses / vhpiCbRepEndOfProcesses - End of process execution

❌ Not Implemented Callback Reasons

The following 32 callback reasons will result in an "unsupported reason" error:

Statement-Level Callbacks

• vhpiCbStmt - Statement execution
• vhpiCbResume / vhpiCbSuspend - Process suspend/resume
• vhpiCbStartOfSubpCall / vhpiCbEndOfSubpCall - Subprogram calls

Signal Callbacks

• vhpiCbForce / vhpiCbRelease - Signal forcing
• vhpiCbTransaction - Signal transactions

Simulation Control Callbacks

• vhpiCbStartOfPostponed / vhpiCbRepStartOfPostponed - Postponed processes

Tool/Analysis Phase Callbacks

• vhpiCbStartOfTool / vhpiCbEndOfTool
• vhpiCbStartOfAnalysis / vhpiCbEndOfAnalysis
• vhpiCbStartOfElaboration / vhpiCbEndOfElaboration

Save/Restore Callbacks

• vhpiCbStartOfSave / vhpiCbEndOfSave
• vhpiCbStartOfRestart / vhpiCbEndOfRestart
• vhpiCbStartOfReset / vhpiCbEndOfReset

Interactive/Error Callbacks

• vhpiCbQuiescense - Simulation quiescence
• vhpiCbPLIError - PLI errors
• vhpiCbEnterInteractive / vhpiCbExitInteractive - Interactive mode
• vhpiCbSigInterrupt - Signal interrupts

Foreign Model Callbacks

• vhpiCbTimeOut / vhpiCbRepTimeOut - Timeout events
• vhpiCbSensitivity - Sensitivity list changes

Value Format Support

NVC supports only a subset of VHPI value formats - many types return "not supported":

✅ Supported Value Formats

Scalar Formats

• vhpiEnumVal / vhpiSmallEnumVal - Enumeration values (based on literal count)
• vhpiIntVal - Integer values
• vhpiRealVal - Real number values
• vhpiLogicVal - Single std_logic/std_ulogic values
• vhpiCharVal - Character values (for std.standard.character)

String/Vector Formats

• vhpiStrVal - String values (for character arrays)
• vhpiLogicVecVal - std_logic/std_ulogic vectors with mapping
• vhpiSmallEnumVecVal / vhpiEnumVecVal - Enumeration vectors
• vhpiRealVecVal - Real number vectors
• vhpiIntVecVal - Integer vectors

❌ Unsupported Value Formats

The following formats will return "not supported" (-1):

• vhpiTimeVal / vhpiPhysVal / vhpiSmallPhysVal - Time/physical values
• vhpiBinStrVal / vhpiOctStrVal / vhpiDecStrVal / vhpiHexStrVal - String representations
• vhpiTimeVecVal / vhpiPhysVecVal / vhpiSmallPhysVecVal - Time/physical vectors
• vhpiPtrVal / vhpiPtrVecVal - Pointer values
• vhpiRawDataVal - Raw data format
• vhpiObjTypeVal - Object type values
• Many other specialized formats

Put Value Mode Support

NVC supports only some vhpi_put_value modes:

✅ Supported Modes

• vhpiDeposit / vhpiDepositPropagate - For signals and variables
• vhpiForce / vhpiForcePropagate - For signals and variables
• vhpiRelease - For signals (releases force) and variables (no effect)

❌ Unsupported Modes

• vhpiSizeConstraint - Will result in "mode not supported" error

Simulation Control Support

NVC supports only basic simulation control:

✅ Supported Commands

• vhpiStop - Stop simulation
• vhpiFinish - Finish simulation

❌ Unsupported Commands

• vhpiReset - Will result in "vhpiReset not supported" error

Foreign Model Support

NVC supports only function/procedure foreign models:

✅ Supported Foreign Kinds

• vhpiFuncF - Foreign functions
• vhpiProcF - Foreign procedures

❌ Unsupported Foreign Kinds

• vhpiArchF - Foreign architectures
• vhpiLibF - Foreign libraries
• vhpiAppF - Foreign applications

Limitations Summary

1. Protected Types: vhpi_protected_call() is not implemented
2. Transaction Scheduling: vhpi_schedule_transaction() is not implemented
3. Value Formatting: vhpi_format_value() is not implemented
4. Object Creation: vhpi_create() is not implemented
5. Save/Restore: Foreign model data save/restore functions not implemented
6. Limited Callback Support: Only 17 out of 49 callback reasons implemented
7. Limited Value Formats: Many value formats return "not supported"
8. No Reset Support: vhpiReset simulation control not supported
9. Limited Foreign Models: Only functions/procedures supported

[nickg]

There can be mistakes.

Have you checked this? I'd rather not blindly copy AI output without some human editing.

[Blebowski]

Hi, no, I have not checked that, damn AI...

[metebalci]

I did a few iterations when generating this but I have not used all the functions and didnt check all against the nvc code, hence the note there can be mistakes.

[Blebowski]

I tend to agree with @nickg not to put in AI generated code. I would do so only if being absolutely certain it is correct.
I see lot of hallucinations last couple of days as I use AI for Proof-reading of technical documentation I write at my work.

[metebalci]

I guess we are saying the same thing. I dont think it matters how it is generated, it has to be verified anyway for sure. (and I cant verify all, at least not in a short time)