small update

Don't throw away the right hand time of changes

README.md

@@ -1,4 +1,4 @@
-Copyright - Yehowshua Immanuel
+Copyright(2023) - Yehowshua Immanuel
 
 # Vision
 Imagine being able to visualize a CPU pipeline diagram by merely loading a simulation waveform dump, sprinkling in a bit of code, and dragging and dropping some diagram blocks into the visualizer. This project aims to offer such an experience.
@@ -6,10 +6,7 @@ Imagine being able to visualize a CPU pipeline diagram by merely loading a simul
 Since this project is written in Rust, it should also be able to run in the browser via web-assembly.
 
 # Status
-I hope to work on this more actively again soon.
+As of January 2024, work on the Fastwave Backend is stalled. It has been a fun journey watching Fastwave enable the first iterations of the [surfer waveform viewer](https://surfer-project.org). Now surfer uses an even better backend called [Wellen](https://github.com/ekiwi/wellen?tab=readme-ov-file). Go check it out! I hear it's really good. Perhaps I will soon archive the Fastwave Backend.
-
-The Zoq is is working on an excellent frontend call the Surfer. Check it out 
-[here](https://gitlab.com/surfer-project/surfer)!
 
 Browser demo: https://app.surfer-project.org/
 

src/lib.rs

@@ -5,7 +5,7 @@
 
 mod vcd;
 pub use vcd::parse::parse_vcd;
-pub use vcd::signal::{Signal, SignalType, SignalValue};
+pub use vcd::signal::{Signal, SignalType, SignalValue, SignalErrors};
 pub use vcd::types::{Metadata, Timescale, Version};
 pub use vcd::types::{ScopeIdx, SignalIdx, VCD};
 

src/vcd/parse/scopes.rs

@@ -289,87 +289,154 @@ fn parse_scopes_inner<R: std::io::Read>(
     // $scope module reg_mag_i $end
     //               ^^^^^^^^^ - scope name
     let (scope_name, _) = next_word!(word_reader)?;
+    // In some cases there are VCD files which have scopes without names.
+    // since these occur in the wild, we'll tolerate them even if it is unclear
+    // if it is supported or not by the spec.
+    if scope_name != "$end" {
+        let mut path = path.clone();
+        path.push(scope_name.to_string());
 
-    let mut path = path.clone();
+        let curr_scope_idx = ScopeIdx(vcd.all_scopes.len());
-    path.push(scope_name.to_string());
 
-    let curr_scope_idx = ScopeIdx(vcd.all_scopes.len());
+        // register this scope as a child of the current parent scope
-
+        // if there is a parent scope, or else we register this scope as
-    // register this scope as a child of the current parent scope
+        // root scope
-    // if there is a parent scope, or else we register this scope as
+        match parent_scope_idx {
-    // root scope
+            Some(ScopeIdx(parent_scope_idx)) => {
-    match parent_scope_idx {
+                let parent_scope = vcd.all_scopes.get_mut(parent_scope_idx).unwrap();
-        Some(ScopeIdx(parent_scope_idx)) => {
+                parent_scope.child_scopes.push(curr_scope_idx);
-            let parent_scope = vcd.all_scopes.get_mut(parent_scope_idx).unwrap();
+            }
-            parent_scope.child_scopes.push(curr_scope_idx);
+            None => vcd.root_scopes.push(curr_scope_idx),
         }
-        None => vcd.root_scopes.push(curr_scope_idx),
-    }
 
-    // add this scope to list of existing scopes
+        // add this scope to list of existing scopes
-    vcd.all_scopes.push(Scope {
+        vcd.all_scopes.push(Scope {
-        name: scope_name.to_string(),
+            name: scope_name.to_string(),
-        self_idx: curr_scope_idx,
+            self_idx: curr_scope_idx,
-        child_signals: vec![],
+            child_signals: vec![],
-        child_scopes: vec![],
+            child_scopes: vec![],
-    });
+        });
 
-    // $scope module reg_mag_i $end
+        // $scope module reg_mag_i $end
-    //                         ^^^^ - end keyword
+        //                         ^^^^ - end keyword
-    ident(word_reader, "$end")?;
+        ident(word_reader, "$end")?;
 
-    loop {
+        loop {
-        let (word, cursor) = next_word!(word_reader)?;
+            let (word, cursor) = next_word!(word_reader)?;
-        let ParseResult { matched, residual } = tag(word, "$");
+            let ParseResult { matched, residual } = tag(word, "$");
-        match matched {
+            match matched {
-            // we hope that this word starts with a `$`
+                // we hope that this word starts with a `$`
-            "$" => {
+                "$" => {
-                match residual {
+                    match residual {
-                    "scope" => {
+                        "scope" => {
-                        // recursive - parse inside of current scope tree
+                            // recursive - parse inside of current scope tree
-                        parse_scopes_inner(
+                            parse_scopes_inner(
-                            word_reader,
+                                word_reader,
-                            Some(curr_scope_idx),
+                                Some(curr_scope_idx),
-                            vcd,
+                                vcd,
-                            signal_map,
+                                signal_map,
-                            &path,
+                                &path,
-                        )?;
+                            )?;
-                    }
+                        }
-                    "var" => {
+                        "var" => {
-                        parse_var(word_reader, curr_scope_idx, vcd, signal_map, &path)?;
+                            parse_var(word_reader, curr_scope_idx, vcd, signal_map, &path)?;
-                    }
+                        }
-                    "upscope" => {
+                        "upscope" => {
-                        ident(word_reader, "$end")?;
+                            ident(word_reader, "$end")?;
-                        break;
-                    }
-                    // we ignore comments
-                    "comment" => loop {
-                        if ident(word_reader, "$end").is_ok() {
                             break;
                         }
-                    },
+                        // we ignore comments
-                    _ => {
+                        "comment" => loop {
-                        let err = format!(
+                            if ident(word_reader, "$end").is_ok() {
-                            "Error near {}:{}. \
+                                break;
-                                           found keyword `{residual}` but expected \
+                            }
-                                           `$scope`, `$var`, `$comment`, or `$upscope` \
+                        },
-                                           on {cursor:?}",
+                        _ => {
-                            file!(),
+                            let err = format!(
-                            line!()
+                                "Error near {}:{}. \
-                        );
+                                               found keyword `{residual}` but expected \
-                        return Err(err);
+                                               `$scope`, `$var`, `$comment`, or `$upscope` \
+                                               on {cursor:?}",
+                                file!(),
+                                line!()
+                            );
+                            return Err(err);
+                        }
                     }
                 }
+                _ => {
+                    let err = format!(
+                        "Error near {}:{}. \
+                                      found keyword `{matched}` but \
+                                      expected `$` on {cursor:?}",
+                        file!(),
+                        line!()
+                    );
+                    return Err(err);
+                }
             }
-            _ => {
+        }
-                let err = format!(
+    } else {
-                    "Error near {}:{}. \
+        // We'll be conservative and only allow new scopes in this case, and make the nameless
-                                  found keyword `{matched}` but \
+        // scope completely transparent. I.e.
-                                  expected `$` on {cursor:?}",
+        // $scope module a $end
-                    file!(),
+        //   $scope module $end
-                    line!()
+        //     $scope module b $end
-                );
+        //       ...
-                return Err(err);
+        //     $upscope
+        //   $upscope
+        // $upscope
+        // will create `a.b`
+        loop {
+            let (word, cursor) = next_word!(word_reader)?;
+            let ParseResult { matched, residual } = tag(word, "$");
+            match matched {
+                // we hope that this word starts with a `$`
+                "$" => {
+                    match residual {
+                        "scope" => {
+                            // recursive - parse inside of current scope tree
+                            parse_scopes_inner(
+                                word_reader,
+                                parent_scope_idx,
+                                vcd,
+                                signal_map,
+                                &path,
+                            )?;
+                        }
+                        "upscope" => {
+                            ident(word_reader, "$end")?;
+                            break;
+                        }
+                        // we ignore comments
+                        "comment" => loop {
+                            if ident(word_reader, "$end").is_ok() {
+                                break;
+                            }
+                        },
+                        _ => {
+                            let err = format!(
+                                "Error near {}:{}. \
+                                               found keyword `{residual}` in annonyoums scope but expected \
+                                               `$scope`, `$comment`, or `$upscope` \
+                                               on {cursor:?}",
+                                file!(),
+                                line!()
+                            );
+                            return Err(err);
+                        }
+                    }
+                }
+                _ => {
+                    let err = format!(
+                        "Error near {}:{}. \
+                                      found keyword `{matched}` but \
+                                      expected `$` on {cursor:?}",
+                        file!(),
+                        line!()
+                    );
+                    return Err(err);
+                }
             }
         }
     }

src/vcd/signal.rs

@@ -11,7 +11,7 @@ use num::BigUint;
 #[derive(Debug, Copy, Clone)]
 pub struct LsbIdxOfTmstmpValOnTmln(pub(super) u32);
 
-#[derive(Debug, Eq, PartialEq)]
+#[derive(Debug, Eq, PartialEq, Clone)]
 pub enum SignalType {
     Event,
     Integer,
@@ -40,6 +40,11 @@ pub enum SignalValue {
     String(String),
 }
 
+pub struct QueryResult<T> {
+    pub current: Option<(TimeStamp, T)>,
+    pub next: Option<TimeStamp>,
+}
+
 pub struct Signal<'a>(pub(super) &'a SignalEnum);
 
 impl<'a> Signal<'a> {
@@ -48,11 +53,16 @@ impl<'a> Signal<'a> {
         signal_enum.name()
     }
 
-    pub fn name_with_size(&self) -> String {
+    pub fn name_with_index(&self) -> String {
         let Signal(signal_enum) = &self;
         signal_enum.name_with_index()
     }
 
+    pub fn index(&self) -> Option<String> {
+        let Signal(signal_enum) = &self;
+        signal_enum.index()
+    }
+
     pub fn path(&self) -> &[String] {
         match self.0 {
             SignalEnum::Data { path, .. } => path,
@@ -77,6 +87,9 @@ impl<'a> Signal<'a> {
         signal_enum.bits_required()
     }
 
+    // NOTE: (zoq) I am removing thse because they aren't used in Surfer so I can't test them
+    // properly
+    /*
     pub fn query_string_val_on_tmln(
         &self,
         desired_time: &BigUint,
@@ -85,32 +98,33 @@ impl<'a> Signal<'a> {
         let Signal(signal_enum) = &self;
         signal_enum
             .query_string_val_on_tmln(desired_time, &vcd.tmstmps_encoded_as_u8s, &vcd.all_signals)
-            .map(|(val, _)| val)
+            .map(|QueryResult{current, next: _}| current.map(|c| c.1))
     }
 
     pub fn query_num_val_on_tmln(
         &self,
         desired_time: &BigUint,
         vcd: &types::VCD,
-    ) -> Result<BigUint, SignalErrors> {
+    ) -> Result<Option<BigUint>, SignalErrors> {
         let Signal(signal_enum) = &self;
         signal_enum
             .query_num_val_on_tmln(desired_time, &vcd.tmstmps_encoded_as_u8s, &vcd.all_signals)
-            .map(|(val, _)| val)
+            .map(|QueryResult{current, next: _}| current.map(|c| c.1))
     }
+    */
 
     pub fn query_val_on_tmln(
         &self,
         desired_time: &BigUint,
         vcd: &types::VCD,
-    ) -> Result<(TimeStamp, SignalValue), SignalErrors> {
+    ) -> Result<QueryResult<SignalValue>, SignalErrors> {
         let Signal(signal_enum) = &self;
-        let num_val = signal_enum.query_num_val_on_tmln(
+        let num_query_out = signal_enum.query_num_val_on_tmln(
             desired_time,
             &vcd.tmstmps_encoded_as_u8s,
             &vcd.all_signals,
         );
-        let str_val = signal_enum.query_string_val_on_tmln(
+        let str_query_out = signal_enum.query_string_val_on_tmln(
             desired_time,
             &vcd.tmstmps_encoded_as_u8s,
             &vcd.all_signals,
@@ -119,16 +133,44 @@ impl<'a> Signal<'a> {
         // Both num and str will return the newest value that is closest to
         // the desired time. If both have valid values, select the most recent
         // one
-        match (num_val, str_val) {
+        match (num_query_out, str_query_out) {
-            (Ok((num_val, num_time)), Ok((str_val, str_time))) => {
+            (Ok(num_result), Ok(str_result)) => {
-                if num_time > str_time {
+                let next = match (num_result.next, str_result.next) {
-                    Ok((num_time, SignalValue::BigUint(num_val)))
+                    (Some(n), Some(s)) => Some(n.min(s)),
-                } else {
+                    (Some(n), None) => Some(n),
-                    Ok((str_time, SignalValue::String(str_val)))
+                    (None, Some(s)) => Some(s),
+                    (None, None) => None,
+                };
+
+                match (num_result.current, str_result.current) {
+                    (Some((num_time, num_value)), Some((str_time, str_value))) => {
+                        if num_time > str_time {
+                            Ok(QueryResult {
+                                current: Some((num_time, SignalValue::BigUint(num_value))),
+                                next,
+                            })
+                        } else {
+                            Ok(QueryResult {
+                                current: Some((str_time, SignalValue::String(str_value))),
+                                next,
+                            })
+                        }
+                    }
+                    (Some((num_time, num_val)), None) => Ok(QueryResult {
+                        current: Some((num_time, SignalValue::BigUint(num_val))),
+                        next,
+                    }),
+                    (None, Some((str_time, str_value))) => Ok(QueryResult {
+                        current: Some((str_time, SignalValue::String(str_value))),
+                        next,
+                    }),
+                    (None, None) => Ok(QueryResult {
+                        current: None,
+                        next,
+                    }),
                 }
             }
-            (Ok((num_val, time)), Err(_)) => Ok((time, SignalValue::BigUint(num_val))),
+            (_e, Err(e)) => Err(e),
-            (Err(_), Ok((str_val, time))) => Ok((time, SignalValue::String(str_val))),
             (Err(e), _e) => Err(e),
         }
     }
@@ -187,10 +229,6 @@ pub(super) enum SignalEnum {
 
 #[derive(Debug)]
 pub enum SignalErrors {
-    PreTimeline {
-        desired_time: BigUint,
-        timeline_start_time: BigUint,
-    },
     EmptyTimeline,
     TimelineNotMultiple,
     StrTmlnLenMismatch,
@@ -240,6 +278,13 @@ impl SignalEnum {
             SignalEnum::Alias { name, .. } => name.clone(),
         }
     }
+
+    pub fn index(&self) -> Option<String> {
+        match self {
+            SignalEnum::Data { index, .. } => index.clone(),
+            SignalEnum::Alias { .. } => None,
+        }
+    }
 }
 
 // helper functions ultimately used by Signal's query functions later on
@@ -384,7 +429,7 @@ impl SignalEnum {
         desired_time: &BigUint,
         tmstmps_encoded_as_u8s: &Vec<u8>,
         all_signals: &Vec<SignalEnum>,
-    ) -> Result<(String, TimeStamp), SignalErrors> {
+    ) -> Result<QueryResult<String>, SignalErrors> {
         let signal_idx = match self {
             Self::Data { self_idx, .. } => {
                 let SignalIdx(idx) = self_idx;
@@ -418,7 +463,10 @@ impl SignalEnum {
         // this signal should at least have some events, otherwise, trying to index into
         // an empty vector later on would fail
         if lsb_indxs_of_string_tmstmp_vals_on_tmln.is_empty() {
-            return Err(SignalErrors::EmptyTimeline);
+            return Ok(QueryResult {
+                current: None,
+                next: None
+            });
         }
 
         // the vector of string timeline lsb indices should have the same
@@ -432,9 +480,9 @@ impl SignalEnum {
         let (timeline_start_time, _) =
             self.time_and_str_val_at_event_idx(0, tmstmps_encoded_as_u8s)?;
         if *desired_time < timeline_start_time {
-            return Err(SignalErrors::PreTimeline {
+            return Ok(QueryResult {
-                desired_time: desired_time.clone(),
+                current: None,
-                timeline_start_time,
+                next: Some(timeline_start_time),
             });
         }
 
@@ -446,7 +494,10 @@ impl SignalEnum {
         // check if we're requesting a value that occurs beyond the end of the timeline,
         // if so, return the last value in this timeline
         if *desired_time > timeline_end_time {
-            return Ok((timeline_end_val.to_string(), timeline_end_time));
+            return Ok(QueryResult {
+                current: Some((timeline_end_time, timeline_end_val.to_string())),
+                next: None,
+            });
         }
 
         // This while loop is the meat of the lookup. Performance is log2(n),
@@ -465,7 +516,21 @@ impl SignalEnum {
                     lower_idx = mid_idx + 1;
                 }
                 std::cmp::Ordering::Equal => {
-                    return Ok((curr_val.to_string(), curr_time));
+                    let next_time = if mid_idx < lsb_indxs_of_string_tmstmp_vals_on_tmln.len() - 1 {
+                        Some(
+                            self.time_and_str_val_at_event_idx(
+                                mid_idx + 1,
+                                tmstmps_encoded_as_u8s,
+                            )?
+                            .0,
+                        )
+                    } else {
+                        None
+                    };
+                    return Ok(QueryResult {
+                        current: Some((curr_time, curr_val.to_string())),
+                        next: next_time,
+                    });
                 }
                 std::cmp::Ordering::Greater => {
                     upper_idx = mid_idx - 1;
@@ -488,14 +553,17 @@ impl SignalEnum {
             });
         }
 
-        Ok((left_val.to_string(), left_time))
+        Ok(QueryResult {
+            current: Some((left_time, left_val.to_string())),
+            next: Some(right_time),
+        })
     }
     pub fn query_num_val_on_tmln(
         &self,
         desired_time: &BigUint,
         tmstmps_encoded_as_u8s: &Vec<u8>,
         all_signals: &Vec<SignalEnum>,
-    ) -> Result<(BigUint, TimeStamp), SignalErrors> {
+    ) -> Result<QueryResult<BigUint>, SignalErrors> {
         let signal_idx = match self {
             Self::Data { self_idx, .. } => {
                 let SignalIdx(idx) = self_idx;
@@ -540,7 +608,10 @@ impl SignalEnum {
         // this signal should at least have some events, otherwise, trying to index into
         // an empty vector later on would fail
         if lsb_indxs_of_num_tmstmp_vals_on_tmln.is_empty() {
-            return Err(SignalErrors::EmptyTimeline);
+            return Ok(QueryResult {
+                current: None,
+                next: None
+            });
         }
 
         // assertion that value_sequence is a proper multiple of
@@ -563,9 +634,9 @@ impl SignalEnum {
         let (timeline_start_time, _) =
             self.time_and_num_val_at_event_idx(0, tmstmps_encoded_as_u8s)?;
         if *desired_time < timeline_start_time {
-            return Err(SignalErrors::PreTimeline {
+            return Ok(QueryResult {
-                desired_time: desired_time.clone(),
+                current: None,
-                timeline_start_time,
+                next: Some(timeline_start_time),
             });
         }
 
@@ -577,7 +648,10 @@ impl SignalEnum {
         // check if we're requesting a value that occurs beyond the end of the timeline,
         // if so, return the last value in this timeline
         if *desired_time > timeline_end_time {
-            return Ok((timeline_end_val, timeline_end_time));
+            return Ok(QueryResult {
+                current: Some((timeline_end_time, timeline_end_val)),
+                next: None,
+            });
         }
 
         // This while loop is the meat of the lookup. Performance is log2(n),
@@ -596,7 +670,21 @@ impl SignalEnum {
                     lower_idx = mid_idx + 1;
                 }
                 std::cmp::Ordering::Equal => {
-                    return Ok((curr_val, curr_time));
+                    let next_time = if mid_idx < lsb_indxs_of_num_tmstmp_vals_on_tmln.len() - 1 {
+                        Some(
+                            self.time_and_num_val_at_event_idx(
+                                mid_idx + 1,
+                                tmstmps_encoded_as_u8s,
+                            )?
+                            .0,
+                        )
+                    } else {
+                        None
+                    };
+                    return Ok(QueryResult {
+                        current: Some((curr_time, curr_val)),
+                        next: next_time,
+                    });
                 }
                 std::cmp::Ordering::Greater => {
                     upper_idx = mid_idx - 1;
@@ -619,6 +707,9 @@ impl SignalEnum {
             });
         }
 
-        Ok((left_val, left_time))
+        return Ok(QueryResult {
+            current: Some((left_time, left_val)),
+            next: Some(right_time),
+        });
     }
 }

src/vcd/types.rs

@@ -9,7 +9,7 @@ use chrono::prelude::{DateTime, Utc};
 use num::BigUint;
 use std::fmt;
 
-#[derive(Debug)]
+#[derive(Debug, Clone)]
 pub struct Version(pub String);
 
 #[derive(Debug, Clone, Copy, Eq, PartialEq)]