use crate::{
BitRange, BitsRef, Direction, Encoding, Error, Format, Hierarchy, LogicDomain, Metadata,
Packing, Result, Signal, Time, TimeSpan, TimeUnit, Timescale, ValueRef,
hierarchy::{EnumerationData, ScopeData, VariableData},
};
use sha2::{Digest, Sha256};
use std::{
ffi::{CStr, CString, c_char, c_int, c_void},
io::{Read, Seek, SeekFrom},
ops::ControlFlow,
os::unix::ffi::OsStrExt,
os::unix::fs::{MetadataExt, OpenOptionsExt},
path::Path,
ptr::NonNull,
sync::{
Arc, Mutex, OnceLock,
atomic::{AtomicBool, Ordering},
},
};
const BACKEND: &str = "wdb-lib";
static SDK: Mutex<()> = Mutex::new(());
fn lock() -> std::sync::MutexGuard<'static, ()> {
SDK.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
}
#[repr(C)]
#[derive(Clone, Copy, Default)]
struct Meta {
last: u64,
precision: i32,
has_variables: u32,
}
#[repr(C)]
#[derive(Default)]
struct Declaration {
id: u64,
parent: usize,
scope: u32,
encoding: u32,
width: u32,
has_range: u32,
is_constant: u32,
direction: u32,
signedness: u32,
logic_domain: u32,
packing: u32,
name_syntax: u32,
msb: i64,
lsb: i64,
name: *const c_char,
reader_name: *const c_char,
kind: *const c_char,
type_name: *const c_char,
definition: *const c_char,
variants: usize,
base_len: usize,
}
#[repr(C)]
#[derive(Default)]
struct Record {
tick: u64,
id: u64,
encoding: u32,
data: *const u8,
len: usize,
}
const _: () = {
assert!(std::mem::size_of::<Meta>() == 16);
assert!(std::mem::offset_of!(Meta, precision) == 8);
assert!(std::mem::size_of::<Declaration>() == 128);
assert!(std::mem::offset_of!(Declaration, msb) == 56);
assert!(std::mem::offset_of!(Declaration, reader_name) == 80);
assert!(std::mem::offset_of!(Declaration, base_len) == 120);
assert!(std::mem::size_of::<Record>() == 40);
assert!(std::mem::offset_of!(Record, data) == 24);
assert!(std::mem::offset_of!(Record, len) == 32);
};
unsafe extern "C" {
fn ondas_wdb_open(
path: *const c_char,
metadata_only: c_int,
out: *mut *mut c_void,
error: *mut c_char,
cap: usize,
) -> c_int;
fn ondas_wdb_validate_runtime(error: *mut c_char, cap: usize) -> c_int;
fn ondas_wdb_release_indexes(reader: *mut c_void, error: *mut c_char, cap: usize) -> c_int;
fn ondas_wdb_release_storage(reader: *mut c_void, error: *mut c_char, cap: usize) -> c_int;
fn ondas_wdb_close(reader: *mut c_void);
fn ondas_wdb_metadata(reader: *mut c_void, out: *mut Meta);
fn ondas_wdb_decl_count(reader: *mut c_void) -> usize;
fn ondas_wdb_scope_count(reader: *mut c_void) -> usize;
fn ondas_wdb_declaration(reader: *mut c_void, index: usize, out: *mut Declaration) -> c_int;
fn ondas_wdb_enum_variant(
reader: *mut c_void,
declaration: usize,
variant: usize,
bits: *mut *const c_char,
label: *mut *const c_char,
) -> c_int;
fn ondas_wdb_begin(
reader: *mut c_void,
ids: *const u64,
count: usize,
start: u64,
end: u64,
error: *mut c_char,
cap: usize,
) -> c_int;
fn ondas_wdb_begin_points(
handle: *mut c_void,
ids: *const u64,
count: usize,
error: *mut c_char,
cap: usize,
) -> i32;
fn ondas_wdb_sample_bits(
reader: *mut c_void,
id: u64,
time: u64,
lsb: u32,
width: u32,
out: *mut Record,
changed: *mut c_int,
error: *mut c_char,
cap: usize,
) -> c_int;
fn ondas_wdb_next(
reader: *mut c_void,
out: *mut Record,
error: *mut c_char,
cap: usize,
) -> c_int;
fn ondas_wdb_end(reader: *mut c_void);
}
fn backend_error(message: impl Into<String>) -> Error {
Error::Backend {
backend: BACKEND.into(),
operation: "decode",
message: message.into(),
}
}
fn status(code: c_int, error: &[c_char; 512], operation: &'static str) -> Result<()> {
if code >= 0 {
return Ok(());
}
let message = unsafe { CStr::from_ptr(error.as_ptr()) }
.to_string_lossy()
.into_owned();
Err(if code == -4 {
Error::UnsupportedFeature {
format: Format::Wdb,
backend: BACKEND.into(),
operation,
message,
}
} else {
Error::Backend {
backend: BACKEND.into(),
operation,
message,
}
})
}
fn dbg_version(file: &mut (impl Read + Seek), length: u64) -> std::io::Result<Option<u16>> {
let mut header = [0; 0xc8];
if length < header.len() as u64 {
return Ok(None);
}
file.seek(SeekFrom::Start(0))?;
file.read_exact(&mut header)?;
if header[..24] != *b"Xilinx WAVE DATABASE 01\0" {
return Ok(None);
}
let word = |bytes: &[u8]| u64::from_le_bytes(bytes.try_into().unwrap());
let in_bounds = |offset: u64, size: u64| {
offset >= header.len() as u64 && offset <= length && size <= length - offset
};
let mut seen = 0;
let mut debug = None;
let mut ranges = vec![(0, header.len() as u64)];
for pointer in header[0x48..0x60].as_chunks::<8>().0 {
let pointer = word(pointer);
if !in_bounds(pointer, 48) {
return Ok(None);
}
ranges.push((pointer, pointer + 48));
file.seek(SeekFrom::Start(pointer))?;
let mut entry = [0; 48];
file.read_exact(&mut entry)?;
let Some(end) = entry[..24].iter().position(|byte| *byte == 0) else {
return Ok(None);
};
let flag = match &entry[..end] {
b"WDB.Event" => 1,
b"Xilinx RTTI" => 2,
b"Xilinx DBG" => 4,
_ => return Ok(None),
};
let start = word(&entry[32..40]);
let size = word(&entry[40..48]);
if seen & flag != 0 || word(&entry[24..32]) != 1 || !in_bounds(start, size) {
return Ok(None);
}
if (flag == 1 && size != 72) || (flag == 2 && size < 40) || (flag == 4 && size < 184) {
return Ok(None);
}
ranges.push((start, start + size));
seen |= flag;
if flag == 4 {
debug = Some((start, size));
}
}
ranges.sort_unstable();
if ranges.windows(2).any(|pair| pair[0].1 > pair[1].0) {
return Ok(None);
}
let Some((start, _)) = debug else {
return Ok(None);
};
file.seek(SeekFrom::Start(start))?;
let mut signature = [0; 20];
file.read_exact(&mut signature)?;
if !signature.starts_with(b"Xilinx ISim DBG ")
|| !signature[16..19].iter().all(u8::is_ascii_digit)
|| signature[19] != 0
{
return Ok(None);
}
Ok(std::str::from_utf8(&signature[16..19])
.ok()
.and_then(|version| version.parse().ok()))
}
unsafe fn string(pointer: *const c_char) -> Result<Option<String>> {
if pointer.is_null() {
return Ok(None);
}
unsafe { CStr::from_ptr(pointer) }
.to_str()
.map(|s| Some(s.to_owned()))
.map_err(|_| backend_error("non-UTF-8 native metadata"))
}
struct Handle(NonNull<c_void>);
unsafe impl Send for Handle {}
unsafe impl Sync for Handle {}
impl Drop for Handle {
fn drop(&mut self) {
let _lock = lock();
let mut error = [0; 512];
unsafe { ondas_wdb_release_indexes(self.0.as_ptr(), error.as_mut_ptr(), error.len()) };
unsafe { ondas_wdb_close(self.0.as_ptr()) };
}
}
fn preflight(path: &Path, operation: &'static str) -> Result<(CString, std::fs::File, u64)> {
let malformed = || Error::Malformed {
format: Format::Wdb,
backend: BACKEND.into(),
message: "invalid or truncated WDB container header".into(),
};
let mut file = std::fs::File::open(path)?;
let length = file.metadata()?.len();
if length < 0xc8 {
return Err(malformed());
}
let mut header = [0; 24];
file.read_exact(&mut header)?;
if !header.starts_with(b"Xilinx WAVE DATABASE ") {
return Err(malformed());
}
if header != *b"Xilinx WAVE DATABASE 01\0" {
return Err(Error::UnsupportedFeature {
format: Format::Wdb,
backend: BACKEND.into(),
operation,
message: "unsupported WDB container version".into(),
});
}
let path = CString::new(path.as_os_str().as_bytes()).map_err(|_| {
Error::Io(std::io::Error::new(
std::io::ErrorKind::InvalidInput,
"NUL in WDB path",
))
})?;
Ok((path, file, length))
}
fn preflight_evicting(
path: &Path,
operation: &'static str,
) -> Result<(CString, std::fs::File, u64)> {
match preflight(path, operation) {
Ok(opened) => Ok(opened),
Err(error) => {
evict_idle();
Err(error)
}
}
}
fn identity_holds(path: &[u8], file: &std::fs::File, identity: &NativeIdentity) -> bool {
let Some(from_path) = file_metadata(path) else {
return false;
};
let Ok(from_descriptor) = file.metadata() else {
return false;
};
from_path == identity.metadata
&& metadata_key(&from_descriptor) == Some(identity.metadata.clone())
}
fn validate_runtime() -> Result<()> {
let mut error = [0; 512];
let _lock = lock();
let code = unsafe { ondas_wdb_validate_runtime(error.as_mut_ptr(), error.len()) };
status(code, &error, "open")
}
fn native_open(
path: &CString,
metadata_only: bool,
file: &mut std::fs::File,
length: u64,
) -> Result<Handle> {
let operation = if metadata_only {
"read metadata"
} else {
"open"
};
let mut raw = std::ptr::null_mut();
let mut error = [0; 512];
{
let _lock = lock();
let code = unsafe {
ondas_wdb_open(
path.as_ptr(),
metadata_only.into(),
&mut raw,
error.as_mut_ptr(),
error.len(),
)
};
if let Err(error) = status(code, &error, operation) {
let reader_version = env!("ONDAS_WDB_DBG_VERSION").parse::<u16>().unwrap();
if code == -1
&& reader_version != 0
&& let Ok(Some(version)) = dbg_version(file, length)
&& version > reader_version
{
return Err(Error::UnsupportedFeature {
format: Format::Wdb,
backend: BACKEND.into(),
operation,
message: format!(
"WDB DBG version {version:03} is newer than Reader DBG {reader_version:03}"
),
});
}
return Err(error);
}
}
Ok(Handle(
NonNull::new(raw).ok_or_else(|| backend_error("null native reader"))?,
))
}
fn metadata(meta: Meta, source_name: String) -> Result<Metadata> {
let exponent = meta.precision;
if !(-21..=2).contains(&exponent) {
return Err(backend_error("unsupported native timescale exponent"));
}
let unit = match exponent.div_euclid(3) * 3 {
0 => TimeUnit::Second,
-3 => TimeUnit::Millisecond,
-6 => TimeUnit::Microsecond,
-9 => TimeUnit::Nanosecond,
-12 => TimeUnit::Picosecond,
-15 => TimeUnit::Femtosecond,
-18 => TimeUnit::Attosecond,
-21 => TimeUnit::Zeptosecond,
_ => return Err(backend_error("unsupported native timescale exponent")),
};
Ok(Metadata {
source_name,
timescale: Some(Timescale::new(
10u32.pow(exponent.rem_euclid(3) as u32),
unit,
)),
time_span: (meta.has_variables != 0)
.then(|| TimeSpan::new(Time::ZERO, Time::from_ticks(meta.last))),
writer: None,
date: None,
comments: Vec::new(),
})
}
pub(crate) fn read_metadata(path: &Path, name: String) -> Result<Metadata> {
let (path, mut file, length) = preflight_evicting(path, "read metadata")?;
evict_idle();
let handle = native_open(&path, true, &mut file, length)?;
let mut meta = Meta::default();
unsafe { ondas_wdb_metadata(handle.0.as_ptr(), &mut meta) };
metadata(meta, name)
}
struct Traversal<'a>(&'a mut Handle);
impl Drop for Traversal<'_> {
fn drop(&mut self) {
let _lock = lock();
unsafe { ondas_wdb_end(self.0.0.as_ptr()) };
}
}
#[derive(Clone, PartialEq, Eq)]
struct NativeMetadata {
dev: u64,
ino: u64,
size: u64,
mtime: i64,
mtime_nsec: i64,
ctime: i64,
ctime_nsec: i64,
}
#[derive(Clone, PartialEq, Eq)]
struct NativeIdentity {
metadata: NativeMetadata,
digest: [u8; 32],
}
fn metadata_key(meta: &std::fs::Metadata) -> Option<NativeMetadata> {
meta.file_type().is_file().then(|| NativeMetadata {
dev: meta.dev(),
ino: meta.ino(),
size: meta.size(),
mtime: meta.mtime(),
mtime_nsec: meta.mtime_nsec(),
ctime: meta.ctime(),
ctime_nsec: meta.ctime_nsec(),
})
}
fn file_metadata(path: &[u8]) -> Option<NativeMetadata> {
metadata_key(&std::fs::metadata(std::ffi::OsStr::from_bytes(path)).ok()?)
}
fn content_identity(path: &[u8]) -> Option<NativeIdentity> {
let before = file_metadata(path)?;
let mut file = std::fs::OpenOptions::new()
.read(true)
.custom_flags(libc::O_NONBLOCK)
.open(std::ffi::OsStr::from_bytes(path))
.ok()?;
if metadata_key(&file.metadata().ok()?)? != before {
return None;
}
let mut hasher = Sha256::new();
let mut buffer = [0u8; 64 * 1024];
let mut remaining = before.size;
while remaining > 0 {
let want = remaining.min(buffer.len() as u64) as usize;
let read = file.read(&mut buffer[..want]).ok()?;
if read == 0 {
return None;
}
hasher.update(&buffer[..read]);
remaining -= read as u64;
}
let mut extra = [0u8; 1];
if file.read(&mut extra).ok()? != 0 {
return None;
}
if metadata_key(&file.metadata().ok()?)? != before
|| file_metadata(path) != Some(before.clone())
{
return None;
}
let mut digest = [0u8; 32];
digest.copy_from_slice(&hasher.finalize());
Some(NativeIdentity {
metadata: before,
digest,
})
}
struct Presentation {
ids: Vec<u64>,
indices: Vec<usize>,
encodings: Vec<Encoding>,
hierarchy: Hierarchy,
meta: Meta,
}
struct Idle {
path: Vec<u8>,
identity: NativeIdentity,
handle: Handle,
presentation: Presentation,
}
static IDLE: Mutex<Option<Idle>> = Mutex::new(None);
fn take_idle(path: &[u8], identity: &NativeIdentity) -> Option<Idle> {
let _lock = lock();
let mut idle = IDLE.lock().unwrap_or_else(|poisoned| poisoned.into_inner());
let candidate = idle.as_ref()?;
if candidate.path.as_slice() == path && &candidate.identity == identity {
idle.take()
} else {
None
}
}
pub(crate) fn release_idle() {
evict_idle();
}
static IDLE_CLEANUP: OnceLock<bool> = OnceLock::new();
fn idle_cleanup_available() -> bool {
*IDLE_CLEANUP.get_or_init(|| {
unsafe { libc::atexit(release_idle_at_exit) == 0 }
})
}
fn parkable(tainted: bool, unwinding: bool, has_identity: bool, cleanup_available: bool) -> bool {
!tainted && !unwinding && has_identity && cleanup_available
}
extern "C" fn release_idle_at_exit() {
let Ok(_lock) = SDK.try_lock() else {
return;
};
let Some(idle) = IDLE.try_lock().ok().and_then(|mut slot| slot.take()) else {
return;
};
let Idle {
handle,
presentation,
..
} = idle;
let handle = std::mem::ManuallyDrop::new(handle);
let mut error = [0; 512];
unsafe { ondas_wdb_release_indexes(handle.0.as_ptr(), error.as_mut_ptr(), error.len()) };
unsafe { ondas_wdb_close(handle.0.as_ptr()) };
drop(presentation);
}
fn evict_idle() {
let stale = {
let _lock = lock();
IDLE.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
.take()
};
drop(stale);
}
pub(crate) struct Reader {
handle: Option<Handle>,
ids: Vec<u64>,
indices: Vec<usize>,
encodings: Vec<Encoding>,
hierarchy: Option<Hierarchy>,
meta: Meta,
path: Vec<u8>,
identity: Option<NativeIdentity>,
tainted: Arc<AtomicBool>,
}
struct TaintOnUnwind(Arc<AtomicBool>);
impl Drop for TaintOnUnwind {
fn drop(&mut self) {
if std::thread::panicking() {
self.0.store(true, Ordering::Relaxed);
}
}
}
impl Drop for Reader {
fn drop(&mut self) {
let Some(handle) = self.handle.take() else {
return;
};
let Some(identity) = self.identity.take() else {
return;
};
if !parkable(
self.tainted.load(Ordering::Relaxed),
std::thread::panicking(),
true,
idle_cleanup_available(),
) {
return;
}
let mut replaced = None;
{
let _lock = lock();
unsafe { ondas_wdb_end(handle.0.as_ptr()) };
let mut error = [0; 512];
let code = unsafe {
ondas_wdb_release_indexes(handle.0.as_ptr(), error.as_mut_ptr(), error.len())
};
let storage = if code >= 0 {
unsafe {
ondas_wdb_release_storage(handle.0.as_ptr(), error.as_mut_ptr(), error.len())
}
} else {
-1
};
if code >= 0 && storage == 0 {
let idle = Idle {
path: std::mem::take(&mut self.path),
identity,
handle,
presentation: Presentation {
ids: std::mem::take(&mut self.ids),
indices: std::mem::take(&mut self.indices),
encodings: std::mem::take(&mut self.encodings),
hierarchy: self
.hierarchy
.take()
.expect("live reader retains its hierarchy"),
meta: self.meta,
},
};
replaced = IDLE
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
.replace(idle);
}
}
drop(replaced);
}
}
impl Reader {
pub(crate) fn open(path: &Path, name: String) -> Result<(Self, Hierarchy, Metadata)> {
let (path, mut file, length) = preflight_evicting(path, "open")?;
let path_bytes = path.as_bytes().to_vec();
let identity = content_identity(&path_bytes);
let hit = match identity.as_ref() {
Some(identity) => take_idle(&path_bytes, identity),
None => None,
};
let (handle, presentation) = match hit {
Some(idle) => {
validate_runtime()?;
(idle.handle, idle.presentation)
}
None => {
evict_idle();
let handle = native_open(&path, false, &mut file, length)?;
let presentation = build_presentation(&handle)?;
(handle, presentation)
}
};
let identity = identity.filter(|identity| identity_holds(&path_bytes, &file, identity));
Self::retained(handle, presentation, path_bytes, identity, name)
}
fn retained(
handle: Handle,
presentation: Presentation,
path: Vec<u8>,
identity: Option<NativeIdentity>,
name: String,
) -> Result<(Self, Hierarchy, Metadata)> {
let Presentation {
ids,
indices,
encodings,
hierarchy,
meta,
} = presentation;
let metadata = metadata(meta, name)?;
Ok((
Self {
handle: Some(handle),
ids,
indices,
encodings,
hierarchy: Some(hierarchy.clone()),
meta,
path,
identity,
tainted: Arc::new(AtomicBool::new(false)),
},
hierarchy.reopened(),
metadata,
))
}
}
fn build_presentation(handle: &Handle) -> Result<Presentation> {
{
let mut scopes = Vec::new();
let mut variables = Vec::new();
let mut ids = Vec::new();
let mut indices;
let mut encodings = Vec::new();
let raw = handle.0.as_ptr();
let mut meta = Meta::default();
unsafe {
ondas_wdb_metadata(raw, &mut meta);
let count = ondas_wdb_decl_count(raw);
let scope_count = ondas_wdb_scope_count(raw);
if scope_count > count {
return Err(backend_error("invalid native scope count"));
}
indices = vec![usize::MAX; count];
let mut parents = vec![None; count];
scopes.reserve(scope_count);
variables.reserve(count - scope_count);
for (index, scope_index) in parents.iter_mut().enumerate() {
let mut d = Declaration::default();
if ondas_wdb_declaration(raw, index, &mut d) != 0 {
return Err(backend_error("invalid native declaration index"));
}
let parent = (d.parent != usize::MAX).then_some(d.parent);
let declaration_name_text =
string(d.name)?.ok_or_else(|| backend_error("missing native name"))?;
let (name, name_was_escaped) =
declaration_name(declaration_name_text, d.name_syntax, d.base_len)?;
let reader_name = string(d.reader_name)?;
let kind = declaration_kind(string(d.kind)?.unwrap_or_default(), d.encoding);
if d.scope != 0 {
*scope_index = Some(scopes.len());
scopes.push(ScopeData {
name,
name_was_escaped,
parent,
kind,
definition_name: string(d.definition)?,
packing: match d.packing {
1 => Some(Packing::Packed),
2 => Some(Packing::Unpacked),
_ => None,
},
is_hidden: false,
});
continue;
}
let encoding = match d.encoding {
1 => Encoding::Bits { width: d.width },
2 => Encoding::Real,
3 => Encoding::String,
_ => Encoding::Unsupported,
};
let encoding_index = usize::try_from(d.id)
.ok()
.and_then(|id| indices.get_mut(id))
.ok_or_else(|| backend_error("invalid native history identity"))?;
if *encoding_index == usize::MAX {
*encoding_index = encodings.len();
encodings.push(encoding);
ids.push(d.id);
}
let signal = *encoding_index;
if encodings[signal] != encoding {
return Err(backend_error("incompatible native alias encodings"));
}
let type_name = string(d.type_name)?;
let mut variants = Vec::with_capacity(d.variants);
for variant in 0..d.variants {
let (mut bits, mut label) = (std::ptr::null(), std::ptr::null());
if ondas_wdb_enum_variant(raw, index, variant, &mut bits, &mut label) != 0 {
return Err(backend_error("invalid native enum index"));
}
variants.push((
string(bits)?.ok_or_else(|| backend_error("missing enum code"))?,
string(label)?.ok_or_else(|| backend_error("missing enum label"))?,
));
}
let enumeration = if variants.is_empty() {
None
} else {
EnumerationData::for_encoding(type_name.clone(), variants, encoding)
};
variables.push(VariableData {
reader_name,
name,
name_was_escaped,
parent,
kind,
direction: match d.direction {
1 => Direction::Input,
2 => Direction::Output,
3 => Direction::InOut,
4 => Direction::Buffer,
5 => Direction::Linkage,
_ => Direction::Unknown,
},
range: (d.has_range != 0).then(|| BitRange::new(d.msb, d.lsb)),
is_constant: d.is_constant != 0,
type_name,
signedness: None,
logic_domain: match d.logic_domain {
1 => Some(LogicDomain::TwoState),
2 => Some(LogicDomain::FourState),
3 => Some(LogicDomain::NineState),
_ => None,
},
enumeration,
signal: Some(signal),
});
}
if scopes.len() != scope_count {
return Err(backend_error("inconsistent native scope count"));
}
for parent in scopes
.iter_mut()
.map(|scope| &mut scope.parent)
.chain(variables.iter_mut().map(|variable| &mut variable.parent))
{
if let Some(index) = *parent {
*parent = Some(
parents
.get(index)
.copied()
.flatten()
.ok_or_else(|| backend_error("native parent is not a scope"))?,
);
}
}
}
Ok(Presentation {
ids,
indices,
hierarchy: Hierarchy::new(scopes, variables, encodings.clone()),
encodings,
meta,
})
}
}
impl Reader {
fn attempt<T>(&mut self, run: impl FnOnce(&mut Self) -> Result<T>) -> Result<T> {
let guard = TaintOnUnwind(Arc::clone(&self.tainted));
let result = run(self);
if result.is_err() {
self.tainted.store(true, Ordering::Relaxed);
}
drop(guard);
result
}
pub(crate) fn sample_bits(
&mut self,
bases: &[Signal],
signals: &[Signal],
time: Time,
) -> Result<Vec<crate::Sample>> {
self.attempt(|reader| reader.sample_bits_inner(bases, signals, time))
}
fn sample_bits_inner(
&mut self,
bases: &[Signal],
signals: &[Signal],
time: Time,
) -> Result<Vec<crate::Sample>> {
let ids: Vec<_> = bases
.iter()
.map(|signal| self.ids[signal.index()])
.collect();
let handle = self
.handle
.as_mut()
.ok_or_else(|| backend_error("WDB reader is closed"))?;
let traversal = Traversal(handle);
let mut error = [0; 512];
let _lock = lock();
let code = unsafe {
ondas_wdb_begin_points(
traversal.0.0.as_ptr(),
ids.as_ptr(),
ids.len(),
error.as_mut_ptr(),
error.len(),
)
};
status(code, &error, "begin read")?;
let mut samples = Vec::with_capacity(signals.len());
for &signal in signals {
let width = signal
.width()
.ok_or_else(|| backend_error("point sample requires bits"))?;
let mut record = Record::default();
let mut changed = 0;
let code = unsafe {
ondas_wdb_sample_bits(
traversal.0.0.as_ptr(),
self.ids[signal.index()],
time.ticks(),
signal.lsb(),
width,
&mut record,
&mut changed,
error.as_mut_ptr(),
error.len(),
)
};
status(code, &error, "sample")?;
samples.push(if code == 0 {
crate::Sample::Missing { signal }
} else {
if record.encoding != 1
|| record.len != width as usize
|| record.data.is_null()
|| record.tick > time.ticks()
{
return Err(backend_error("invalid native point bit buffer"));
}
let bytes = unsafe { std::slice::from_raw_parts(record.data, record.len) };
crate::Sample::Value {
signal,
value: crate::Value::Bits(BitsRef::from_validated_ascii(bytes).to_owned()),
changed_at: (changed != 0).then_some(Time::from_ticks(record.tick)),
}
});
}
Ok(samples)
}
pub(crate) fn read<B>(
&mut self,
signals: &[Signal],
end: Time,
visitor: impl for<'v> FnMut(usize, Time, ValueRef<'v>) -> ControlFlow<B>,
) -> Result<ControlFlow<B>> {
self.read_from(signals, Time::ZERO, end, visitor)
}
pub(crate) fn read_from<B>(
&mut self,
signals: &[Signal],
start: Time,
end: Time,
visitor: impl for<'v> FnMut(usize, Time, ValueRef<'v>) -> ControlFlow<B>,
) -> Result<ControlFlow<B>> {
self.attempt(|reader| reader.read_from_inner(signals, start, end, visitor))
}
fn read_from_inner<B>(
&mut self,
signals: &[Signal],
start: Time,
end: Time,
mut visitor: impl for<'v> FnMut(usize, Time, ValueRef<'v>) -> ControlFlow<B>,
) -> Result<ControlFlow<B>> {
if signals.is_empty() || start > end {
return Ok(ControlFlow::Continue(()));
}
let ids: Vec<_> = signals
.iter()
.map(|signal| self.ids[signal.index()])
.collect();
let handle = self
.handle
.as_mut()
.ok_or_else(|| backend_error("WDB reader is closed"))?;
let traversal = Traversal(handle);
let mut error = [0; 512];
{
let _lock = lock();
let code = unsafe {
ondas_wdb_begin(
traversal.0.0.as_ptr(),
ids.as_ptr(),
ids.len(),
start.ticks(),
end.ticks(),
error.as_mut_ptr(),
error.len(),
)
};
status(code, &error, "begin read")?;
}
let mut bytes = Vec::new();
let mut previous = 0;
loop {
let mut record = Record::default();
{
let _lock = lock();
let code = unsafe {
ondas_wdb_next(
traversal.0.0.as_ptr(),
&mut record,
error.as_mut_ptr(),
error.len(),
)
};
status(code, &error, "read")?;
if code == 0 {
break;
}
if record.len > isize::MAX as usize || (record.len != 0 && record.data.is_null()) {
return Err(backend_error("invalid native value buffer"));
}
bytes.clear();
if record.len != 0 {
bytes.extend_from_slice(unsafe {
std::slice::from_raw_parts(record.data, record.len)
});
}
}
if record.tick < previous || record.tick > end.ticks() {
return Err(backend_error("invalid native chronology"));
}
previous = record.tick;
let index = usize::try_from(record.id)
.ok()
.and_then(|id| self.indices.get(id))
.copied()
.filter(|index| *index != usize::MAX)
.ok_or_else(|| backend_error("unknown native history"))?;
let value = match (self.encodings[index], record.encoding) {
(Encoding::Bits { width }, 1) if bytes.len() == width as usize => {
ValueRef::Bits(BitsRef::from_validated_ascii(&bytes))
}
(Encoding::Real, 2) if bytes.len() == 8 => {
ValueRef::Real(f64::from_ne_bytes(bytes.as_slice().try_into().unwrap()))
}
(Encoding::String, 3) => ValueRef::String(crate::value::ascii_string(
&bytes,
Format::Wdb,
BACKEND,
Time::from_ticks(record.tick),
)?),
_ => return Err(backend_error("native value disagrees with declaration")),
};
if let ControlFlow::Break(value) = visitor(index, Time::from_ticks(record.tick), value)
{
return Ok(ControlFlow::Break(value));
}
}
Ok(ControlFlow::Continue(()))
}
}
fn declaration_kind(mut kind: String, encoding: u32) -> String {
if encoding == 3 {
return "string".into();
}
kind.make_ascii_lowercase();
match kind.as_str() {
"enumeration" => "enum".into(),
"float" => "real".into(),
"scope" | "logic" | "bit" | "integer" | "real" | "array" | "record" | "string"
| "event" => kind,
_ => format!("wdb:{kind}"),
}
}
fn declaration_name(mut name: String, syntax: u32, base_len: usize) -> Result<(String, bool)> {
let boundary = if base_len == 0 { name.len() } else { base_len };
let base = name
.get(..boundary)
.ok_or_else(|| backend_error("invalid native array name boundary"))?;
if syntax == 2 && base.len() >= 2 && base.starts_with('\\') && base.ends_with('\\') {
let logical = base[1..base.len() - 1].replace("\\\\", "\\");
name.replace_range(..boundary, &logical);
return Ok((name, false));
}
if syntax != 1 || !base.starts_with('\\') || !base.ends_with(|c: char| c.is_ascii_whitespace())
{
return Ok((name, false));
}
let end = base
.trim_end_matches(|c: char| c.is_ascii_whitespace())
.len();
name.replace_range(end..boundary, "");
name.remove(0);
Ok((name, true))
}
#[cfg(test)]
mod tests {
use super::*;
unsafe extern "C" {
fn ondas_wdb_index_count(reader: *mut c_void) -> usize;
}
fn first_queryable(wave: &crate::Waveform) -> crate::Signal {
wave.hierarchy()
.variables()
.filter_map(|variable| variable.signal())
.find(|signal| !matches!(signal.encoding(), crate::Encoding::Unsupported))
.expect("published fixture must expose a queryable signal")
}
fn scan_once(wave: &mut crate::Waveform) {
let signal = first_queryable(wave);
let outcome = wave
.scan(&[signal], crate::TimeRange::all(), |_| {
std::ops::ControlFlow::<()>::Continue(())
})
.expect("scan published fixture");
assert!(outcome.is_continue());
}
fn live_indexes(wave: &crate::Waveform) -> usize {
let crate::backends::Reader::Wdb(reader) = &wave.reader else {
panic!("expected a wdb-lib waveform");
};
let handle = reader.handle.as_ref().expect("live WDB owner");
let _lock = lock();
unsafe { ondas_wdb_index_count(handle.0.as_ptr()) }
}
fn idle_indexes() -> Option<usize> {
let _lock = lock();
let idle = IDLE.lock().unwrap_or_else(|poisoned| poisoned.into_inner());
let idle = idle.as_ref()?;
Some(unsafe { ondas_wdb_index_count(idle.handle.0.as_ptr()) })
}
#[test]
#[ignore = "requires the selected WDB reader and installed OPB fixtures; run just conformance-wdb"]
fn wdb_drop_releases_every_history_index() {
let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("fixtures/wdb/wdb0301-opb-m/waveform.wdb");
assert!(
path.is_file(),
"missing published fixture {}",
path.display()
);
let mut wave = crate::open_with(&path, BACKEND).expect("open published WDB fixture");
scan_once(&mut wave);
assert!(
live_indexes(&wave) > 0,
"the query built no SDK history index"
);
drop(wave);
match idle_indexes() {
Some(0) | None => {}
Some(kept) => panic!("Drop parked {kept} retained SDK history indexes"),
}
let mut wave = crate::open_with(&path, BACKEND).expect("reopen published WDB fixture");
scan_once(&mut wave);
assert!(
live_indexes(&wave) > 0,
"the reused owner built no fresh SDK history index"
);
drop(wave);
match idle_indexes() {
Some(0) | None => {}
Some(kept) => panic!("the second Drop parked {kept} retained SDK history indexes"),
}
evict_idle();
}
fn container(version: &[u8; 3]) -> Vec<u8> {
let mut bytes = vec![0; 640];
bytes[..24].copy_from_slice(b"Xilinx WAVE DATABASE 01\0");
for (index, (name, start, size)) in [
("WDB.Event", 344_u64, 72_u64),
("Xilinx RTTI", 416, 40),
("Xilinx DBG", 456, 184),
]
.into_iter()
.enumerate()
{
let entry = 200 + index * 48;
bytes[0x48 + index * 8..0x50 + index * 8]
.copy_from_slice(&(entry as u64).to_le_bytes());
bytes[entry..entry + name.len()].copy_from_slice(name.as_bytes());
bytes[entry + 24..entry + 32].copy_from_slice(&1_u64.to_le_bytes());
bytes[entry + 32..entry + 40].copy_from_slice(&start.to_le_bytes());
bytes[entry + 40..entry + 48].copy_from_slice(&size.to_le_bytes());
}
bytes[456..476].copy_from_slice(b"Xilinx ISim DBG 000\0");
bytes[472..475].copy_from_slice(version);
bytes
}
#[test]
fn dbg_version_uses_the_directory_instead_of_embedded_strings() {
let mut bytes = container(b"004");
bytes.extend_from_slice(b"Xilinx ISim DBG 999\0");
let debug = bytes[456..640].to_vec();
bytes.resize(2 * 1024 * 1024, 0);
let start = bytes.len() as u64;
bytes.extend_from_slice(&debug);
bytes[328..336].copy_from_slice(&start.to_le_bytes());
let length = bytes.len() as u64;
assert_eq!(
dbg_version(&mut std::io::Cursor::new(bytes), length).unwrap(),
Some(4)
);
for (signature, expected) in [(b"005", 5), (b"006", 6)] {
let bytes = container(signature);
let length = bytes.len() as u64;
assert_eq!(
dbg_version(&mut std::io::Cursor::new(bytes), length).unwrap(),
Some(expected)
);
}
}
#[test]
fn dbg_version_does_not_classify_invalid_framing() {
let original = container(b"006");
let mut cases = vec![Vec::new(), original[..199].to_vec()];
let mut invalid = original.clone();
invalid[0] = b'!';
cases.push(invalid);
let mut invalid = original.clone();
invalid[0x48..0x50].copy_from_slice(&u64::MAX.to_le_bytes());
cases.push(invalid);
let mut invalid = original.clone();
invalid[328..336].copy_from_slice(&u64::MAX.to_le_bytes());
cases.push(invalid);
let mut invalid = original.clone();
invalid[320..328].copy_from_slice(&2_u64.to_le_bytes());
cases.push(invalid);
let mut invalid = original.clone();
invalid[296..320].copy_from_slice(&original[200..224]);
cases.push(invalid);
let mut invalid = original.clone();
invalid[240..248].copy_from_slice(&8_u64.to_le_bytes());
cases.push(invalid);
let mut invalid = original.clone();
invalid[328..336].copy_from_slice(&200_u64.to_le_bytes());
cases.push(invalid);
let mut invalid = original;
invalid[472] = b'?';
cases.push(invalid);
for bytes in cases {
let length = bytes.len() as u64;
assert_eq!(
dbg_version(&mut std::io::Cursor::new(bytes), length).unwrap(),
None
);
}
}
#[test]
fn invalid_native_precision_returns_an_error() {
for precision in [i32::MIN, -22, 3, i32::MAX] {
assert!(
metadata(
Meta {
precision,
..Meta::default()
},
String::new()
)
.is_err()
);
}
}
#[test]
fn wdb_park_requires_exit_cleanup_and_a_clean_session() {
assert!(!super::parkable(false, false, true, false));
assert!(super::parkable(false, false, true, true));
assert!(!super::parkable(true, false, true, true));
assert!(!super::parkable(false, true, true, true));
assert!(!super::parkable(false, false, false, true));
}
#[test]
#[ignore = "requires the selected reader and installed WDB fixture"]
fn wdb_invalid_native_metadata_indices() {
let path = Path::new(env!("CARGO_MANIFEST_DIR"))
.join("fixtures/wdb/wdb0091-tesbench-behav/waveform.wdb");
let (path, mut file, length) = preflight(&path, "open").unwrap();
let handle = native_open(&path, false, &mut file, length).unwrap();
let raw = handle.0.as_ptr();
let mut declaration = Declaration::default();
let (mut bits, mut label) = (std::ptr::null(), std::ptr::null());
unsafe {
let count = ondas_wdb_decl_count(raw);
assert!(count > 0);
assert_eq!(ondas_wdb_declaration(raw, count, &mut declaration), -1);
assert_eq!(ondas_wdb_declaration(raw, usize::MAX, &mut declaration), -1);
assert_eq!(
ondas_wdb_enum_variant(raw, usize::MAX, 0, &mut bits, &mut label),
-1
);
assert_eq!(
ondas_wdb_enum_variant(raw, 0, usize::MAX, &mut bits, &mut label),
-1
);
assert_eq!(ondas_wdb_declaration(raw, 0, &mut declaration), 0);
assert!(!declaration.name.is_null());
}
}
}