use std::{
fs::File,
io::{BufReader, Cursor},
ops::ControlFlow,
path::Path,
sync::Arc,
};
use crate::{
Error, Hierarchy, Result, Sample, ScanRef, Selection, Signal, Time, TimeRange, TimeSpan,
Timescale, Trace,
backends::{Input, Reader, fst, vcd},
};
pub fn open(path: impl AsRef<Path>) -> Result<Waveform> {
open_file(path.as_ref(), None)
}
pub fn read_metadata(path: impl AsRef<Path>) -> Result<Metadata> {
let path = path.as_ref();
let name = path.to_string_lossy().into_owned();
let file = File::open(path)?;
let vcd_file = file.try_clone().ok();
let mut input: Box<dyn Input> = Box::new(BufReader::new(file));
let format = detect_format(&mut *input, &name, Some(path))?;
match format {
Format::Fst => fst::Reader::open(input, name).map(|(_, _, metadata)| metadata),
Format::Vcd => vcd::Reader::open(input, name, vcd_file).map(|(_, _, metadata)| metadata),
#[cfg(feature = "fsdb-lib")]
Format::Fsdb => crate::backends::fsdb::read_metadata(path, name),
_ => Err(Error::NoBackend { format }),
}
}
pub fn open_with(path: impl AsRef<Path>, backend: &str) -> Result<Waveform> {
open_file(path.as_ref(), Some(backend))
}
pub fn open_bytes(name: impl Into<String>, bytes: Arc<[u8]>) -> Result<Waveform> {
open_input(name.into(), Box::new(Cursor::new(bytes)), None, None, None)
}
pub fn open_bytes_with(
name: impl Into<String>,
bytes: Arc<[u8]>,
backend: &str,
) -> Result<Waveform> {
open_input(
name.into(),
Box::new(Cursor::new(bytes)),
Some(backend),
None,
None,
)
}
fn check_backend(backend: Option<&str>) -> Result<()> {
if let Some(backend) = backend
&& !matches!(backend, "fst-lib" | "vcd-native")
&& !(cfg!(feature = "fsdb-lib") && backend == "fsdb-lib")
{
return Err(Error::UnknownBackend {
backend: backend.into(),
});
}
Ok(())
}
fn open_file(path: &Path, backend: Option<&str>) -> Result<Waveform> {
check_backend(backend)?;
let file = File::open(path)?;
let vcd_file = file.try_clone().ok();
open_input(
path.to_string_lossy().into_owned(),
Box::new(BufReader::new(file)),
backend,
Some(path),
vcd_file,
)
}
fn open_input(
name: String,
mut input: Box<dyn Input>,
backend: Option<&str>,
_path: Option<&Path>,
vcd_file: Option<File>,
) -> Result<Waveform> {
check_backend(backend)?;
#[cfg(feature = "fsdb-lib")]
if backend == Some("fsdb-lib") && _path.is_none() {
return Err(Error::UnsupportedInput {
backend: "fsdb-lib".into(),
input: crate::InputKind::Bytes,
});
}
let format = detect_format(&mut *input, &name, _path)?;
let (reader, hierarchy, metadata) = match (format, backend) {
(Format::Fst, None | Some("fst-lib")) => {
let (reader, hierarchy, metadata) = fst::Reader::open(input, name)?;
(Reader::Fst(Box::new(reader)), hierarchy, metadata)
}
(Format::Vcd, None | Some("vcd-native")) => {
let (reader, hierarchy, metadata) = vcd::Reader::open(input, name, vcd_file)?;
(Reader::Vcd(Box::new(reader)), hierarchy, metadata)
}
#[cfg(feature = "fsdb-lib")]
(Format::Fsdb, None | Some("fsdb-lib")) => {
let path = _path.ok_or_else(|| Error::UnsupportedInput {
backend: "fsdb-lib".into(),
input: crate::InputKind::Bytes,
})?;
let (reader, hierarchy, metadata) = crate::backends::fsdb::Reader::open(path, name)?;
(Reader::Fsdb(Box::new(reader)), hierarchy, metadata)
}
(_, Some(backend)) => {
return Err(Error::BackendDoesNotSupport {
backend: backend.into(),
format,
});
}
(_, None) => return Err(Error::NoBackend { format }),
};
Ok(Waveform {
reader,
hierarchy,
metadata,
})
}
fn detect_format(input: &mut dyn Input, name: &str, _path: Option<&Path>) -> Result<Format> {
let prefix = input.fill_buf()?;
let mut detected =
if prefix.starts_with(&[0, 0, 0, 0, 0, 0, 0, 1, 73]) || prefix.first() == Some(&254) {
Some(Format::Fst)
} else if prefix.starts_with(b"GHDLwave") {
Some(Format::Ghw)
} else {
None
};
if detected.is_none() {
if prefix.starts_with(b"\xef\xbb\xbf") {
input.consume(3);
}
loop {
let prefix = input.fill_buf()?;
if prefix.is_empty() {
break;
}
if let Some(&byte) = prefix.iter().find(|b| !b.is_ascii_whitespace()) {
if byte == b'$' {
detected = Some(Format::Vcd);
}
break;
}
let length = prefix.len();
input.consume(length);
}
}
input.rewind()?;
#[cfg(feature = "fsdb-lib")]
if detected.is_none()
&& let Some(path) = _path
&& crate::backends::fsdb::probe(path)?
{
detected = Some(Format::Fsdb);
}
let extension = Path::new(name)
.extension()
.and_then(|s| s.to_str())
.unwrap_or("")
.to_ascii_lowercase();
if let Some(format) = detected {
Ok(format)
} else {
match extension.as_str() {
"fst" => Ok(Format::Fst),
"vcd" => Ok(Format::Vcd),
"ghw" => Ok(Format::Ghw),
"fsdb" => Ok(Format::Fsdb),
"wlf" => Ok(Format::Wlf),
_ => Err(Error::UnknownFormat),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Format {
Vcd,
Fst,
Ghw,
Fsdb,
Wlf,
}
pub struct Waveform {
pub(crate) reader: Reader,
hierarchy: Hierarchy,
metadata: Metadata,
}
impl Waveform {
pub fn format(&self) -> Format {
match self.reader {
Reader::Vcd(_) => Format::Vcd,
Reader::Fst(_) => Format::Fst,
#[cfg(feature = "fsdb-lib")]
Reader::Fsdb(_) => Format::Fsdb,
#[cfg(test)]
Reader::Memory { .. } | Reader::Generated(_) => Format::Fst,
}
}
pub fn backend(&self) -> &str {
match self.reader {
Reader::Fst(_) => "fst-lib",
Reader::Vcd(_) => "vcd-native",
#[cfg(feature = "fsdb-lib")]
Reader::Fsdb(_) => "fsdb-lib",
#[cfg(test)]
Reader::Memory { .. } => "memory",
#[cfg(test)]
Reader::Generated(_) => "generated",
}
}
pub fn metadata(&self) -> &Metadata {
&self.metadata
}
pub fn hierarchy(&self) -> &Hierarchy {
&self.hierarchy
}
pub fn select(&mut self, signals: &[Signal]) -> Result<Selection<'_>> {
Selection::new(self, signals)
}
pub fn sample(&mut self, signal: Signal, time: Time) -> Result<Sample> {
Ok(self
.samples(&[signal], time)?
.pop()
.expect("one sample for one signal"))
}
pub fn samples(&mut self, signals: &[Signal], time: Time) -> Result<Vec<Sample>> {
self.select(signals)?.samples(time)
}
pub fn trace(&mut self, signal: Signal, range: TimeRange) -> Result<Trace> {
Ok(self
.traces(&[signal], range)?
.pop()
.expect("one trace for one signal"))
}
pub fn traces(&mut self, signals: &[Signal], range: TimeRange) -> Result<Vec<Trace>> {
self.select(signals)?.traces(range)
}
pub fn scan<B>(
&mut self,
signals: &[Signal],
range: TimeRange,
visitor: impl for<'v> FnMut(ScanRef<'v>) -> ControlFlow<B>,
) -> Result<ControlFlow<B>> {
self.select(signals)?.scan(range, visitor)
}
pub fn scan_candidate_times<B>(
&mut self,
signals: &[Signal],
range: TimeRange,
visitor: impl FnMut(Time) -> ControlFlow<B>,
) -> Result<ControlFlow<B>> {
self.select(signals)?.scan_candidate_times(range, visitor)
}
#[cfg(test)]
pub(crate) fn memory(
encodings: Vec<crate::Encoding>,
mut records: Vec<(usize, u64, crate::Value)>,
fail_after: Option<usize>,
) -> Self {
records.sort_by_key(|(_, time, _)| *time);
let span = records.first().zip(records.last()).map(|(first, last)| {
TimeSpan::new(Time::from_ticks(first.1), Time::from_ticks(last.1))
});
Self {
hierarchy: Hierarchy::new(vec![], vec![], encodings),
metadata: Metadata {
source_name: "memory".into(),
timescale: None,
time_span: span,
writer: None,
date: None,
comments: vec![],
},
reader: Reader::Memory {
records: records
.into_iter()
.map(|(id, t, v)| (id, Time::from_ticks(t), v))
.collect(),
fail_after,
},
}
}
}
pub struct Metadata {
pub(crate) source_name: String,
pub(crate) timescale: Option<Timescale>,
pub(crate) time_span: Option<TimeSpan>,
pub(crate) writer: Option<String>,
pub(crate) date: Option<String>,
pub(crate) comments: Vec<String>,
}
impl Metadata {
pub fn source_name(&self) -> &str {
&self.source_name
}
pub fn timescale(&self) -> Option<Timescale> {
self.timescale
}
pub fn time_span(&self) -> Option<TimeSpan> {
self.time_span
}
pub fn writer(&self) -> Option<&str> {
self.writer.as_deref()
}
pub fn date(&self) -> Option<&str> {
self.date.as_deref()
}
pub fn comments(&self) -> impl ExactSizeIterator<Item = &str> + '_ {
self.comments.iter().map(String::as_str)
}
}
#[cfg(test)]
mod semantics_tests;
#[cfg(test)]
mod tests {
use super::*;
fn bytes(text: &[u8]) -> Arc<[u8]> {
Arc::from(text)
}
#[test]
fn detection_prefers_content_and_falls_back_to_case_insensitive_extensions() {
for (name, content, format) in [
("dump.FST", &b" \n$version test $end"[..], Format::Vcd),
("dump.vcd", &b"GHDLwave"[..], Format::Ghw),
("dump.VCD", &b""[..], Format::Vcd),
("dump.GHW", &b""[..], Format::Ghw),
("dump.FSDB", &b""[..], Format::Fsdb),
("dump.WLF", &b""[..], Format::Wlf),
] {
let result = open_bytes(name, bytes(content));
if format == Format::Vcd {
assert!(
matches!(
result,
Err(Error::Malformed {
format: Format::Vcd,
..
})
),
"{name}"
);
} else if cfg!(feature = "fsdb-lib") && format == Format::Fsdb {
assert!(matches!(
result,
Err(Error::UnsupportedInput {
input: crate::InputKind::Bytes,
..
})
));
} else {
assert!(
matches!(result, Err(Error::NoBackend { format: actual }) if actual == format),
"{name}"
);
}
assert!(
matches!(open_bytes_with(name, bytes(content), "fst-lib"), Err(Error::BackendDoesNotSupport { backend, format: actual }) if backend == "fst-lib" && actual == format),
"{name}"
);
}
assert!(
matches!(open_with("", "unknown-reader"), Err(Error::UnknownBackend { backend }) if backend == "unknown-reader")
);
assert!(matches!(open_with("", "fst-lib"), Err(Error::Io(_))));
}
#[test]
fn metadata_preserves_optional_fields_and_comment_order() {
let mut wave = Waveform::memory(vec![], vec![], None);
let metadata = wave.metadata();
assert_eq!(metadata.source_name(), "memory");
assert_eq!(metadata.timescale(), None);
assert_eq!(metadata.time_span(), None);
assert_eq!(metadata.writer(), None);
assert_eq!(metadata.date(), None);
assert_eq!(metadata.comments().len(), 0);
wave.metadata = Metadata {
source_name: "logical name".into(),
timescale: Some(Timescale::new(10, crate::TimeUnit::Picosecond)),
time_span: Some(TimeSpan::new(Time::from_ticks(7), Time::from_ticks(13))),
writer: Some("writer".into()),
date: Some("source date".into()),
comments: vec!["second".into(), "".into(), "first".into(), "second".into()],
};
let metadata = wave.metadata();
assert_eq!(metadata.source_name(), "logical name");
assert_eq!(metadata.writer(), Some("writer"));
assert_eq!(metadata.date(), Some("source date"));
assert_eq!(metadata.timescale().unwrap().factor(), 10);
assert_eq!(
metadata.timescale().unwrap().unit(),
crate::TimeUnit::Picosecond
);
assert_eq!(metadata.time_span().unwrap().first(), Time::from_ticks(7));
assert_eq!(metadata.time_span().unwrap().last(), Time::from_ticks(13));
let mut comments = metadata.comments();
assert_eq!(comments.len(), 4);
assert_eq!(comments.next(), Some("second"));
assert_eq!(comments.len(), 3);
assert_eq!(comments.collect::<Vec<_>>(), ["", "first", "second"]);
}
#[test]
fn opening_errors_distinguish_detection_selection_and_io() {
fn send_sync<T: Send + Sync>() {}
send_sync::<Waveform>();
send_sync::<Hierarchy>();
assert!(matches!(open(""), Err(Error::Io(_))));
assert!(matches!(
open_bytes("unknown", bytes(b"not a waveform")),
Err(Error::UnknownFormat)
));
assert!(matches!(
open_bytes("dump.vcd", bytes(b"$timescale 1 ns $end")),
Err(Error::Malformed {
format: Format::Vcd,
..
})
));
assert!(matches!(
open_bytes_with("dump.vcd", bytes(b"$scope module tb $end"), "fst-lib"),
Err(Error::BackendDoesNotSupport {
format: Format::Vcd,
..
})
));
for backend in ["not-a-reader", "fst-native"] {
assert!(matches!(
open_bytes_with("dump.fst", bytes(b""), backend),
Err(Error::UnknownBackend { backend: actual }) if actual == backend
));
assert!(matches!(
open_with("", backend),
Err(Error::UnknownBackend { backend: actual }) if actual == backend
));
}
assert!(matches!(
open_bytes("empty.fst", bytes(b"")),
Err(Error::Malformed {
format: Format::Fst,
..
})
));
}
}