vpi 0.5.0

Safe and ergonomic Rust bindings to the Verilog and SystemVerilog VPI C API for writing VPI applications in Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

use num_derive::FromPrimitive;
use num_traits::FromPrimitive;

/// Error severity levels reported by VPI.
#[repr(u32)]
#[derive(FromPrimitive, Debug, Clone, PartialEq, Eq)]
pub enum Severity {
    /// Informational notice.
    Notice = vpi_sys::vpiNotice,
    /// Warning that does not necessarily stop simulation.
    Warning = vpi_sys::vpiWarning,
    /// Error condition.
    Error = vpi_sys::vpiError,
    /// Simulator/system-level error.
    System = vpi_sys::vpiSystem,
    /// Internal simulator error.
    Internal = vpi_sys::vpiInternal,
}

impl std::fmt::Display for Severity {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Severity::Notice => write!(f, "Notice"),
            Severity::Warning => write!(f, "Warning"),
            Severity::Error => write!(f, "Error"),
            Severity::System => write!(f, "System"),
            Severity::Internal => write!(f, "Internal"),
        }
    }
}

/// Simulation phase/state where an error occurred.
#[repr(u32)]
#[derive(FromPrimitive, Debug, Clone, PartialEq, Eq)]
pub enum ErrorState {
    /// Compile-time context.
    Compile = vpi_sys::vpiCompile,
    /// PLI callback or API context.
    PLI = vpi_sys::vpiPLI,
    /// Runtime simulation context.
    Run = vpi_sys::vpiRun,
}

impl std::fmt::Display for ErrorState {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ErrorState::Compile => write!(f, "Compile"),
            ErrorState::PLI => write!(f, "PLI"),
            ErrorState::Run => write!(f, "Run"),
        }
    }
}
/// Rich error information returned by `vpi_chk_error`.
#[derive(Debug, Clone)]
pub struct VPIError {
    /// Simulator-defined error code.
    pub code: String,
    /// Human-readable error message.
    pub message: String,
    /// Source file path, when provided by the simulator.
    pub file: Option<String>,
    /// Source line number, or `0` when unavailable.
    pub line: i32,
    /// Optional mapped error severity.
    pub severity: Option<Severity>,
    /// Optional mapped error state.
    pub state: Option<ErrorState>,
    /// Simulator product name reporting the error.
    pub product: String,
}

impl std::fmt::Display for VPIError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let severity_str = self.severity.as_ref().map(|s| s.to_string());
        write!(
            f,
            "[{}] {} ({}:{}) - {}",
            severity_str.as_deref().unwrap_or("Unknown"),
            self.message,
            self.file.as_deref().unwrap_or("Unknown"),
            self.line,
            self.product
        )
    }
}
/// Checks whether the simulator has a pending VPI error.
///
/// Returns `None` when no error is present, otherwise returns the translated
/// [`VPIError`] payload.
#[must_use]
pub fn chk_error() -> Option<VPIError> {
    let mut error_info = vpi_sys::t_vpi_error_info {
        code: std::ptr::null_mut(),
        message: std::ptr::null_mut(),
        file: std::ptr::null_mut(),
        line: 0,
        level: 0,
        state: 0,
        product: std::ptr::null_mut(),
    };
    let error_code = unsafe { vpi_sys::vpi_chk_error(&raw mut error_info) };
    if error_code == 0 {
        None
    } else {
        Some(VPIError {
            code: unsafe { std::ffi::CStr::from_ptr(error_info.code) }
                .to_str()
                .unwrap_or("Unknown")
                .to_string(),
            message: unsafe { std::ffi::CStr::from_ptr(error_info.message) }
                .to_str()
                .unwrap_or("Unknown")
                .to_string(),
            file: if error_info.file.is_null() {
                None
            } else {
                Some(
                    unsafe { std::ffi::CStr::from_ptr(error_info.file) }
                        .to_str()
                        .unwrap_or("Unknown")
                        .to_string(),
                )
            },
            line: error_info.line,
            severity: Severity::from_i32(error_info.level),
            state: ErrorState::from_i32(error_info.state),
            product: unsafe { std::ffi::CStr::from_ptr(error_info.product) }
                .to_str()
                .unwrap_or("Unknown")
                .to_string(),
        })
    }
}

/// Alias of `chk_error` for consistency with rust-vhpi
#[must_use]
pub fn check_error() -> Option<VPIError> {
    chk_error()
}