From c75977eb2ba9084806660082f27d18a0a0caf763 Mon Sep 17 00:00:00 2001
From: Zebreus <lennart@zebre.us>
Date: Sat, 25 May 2024 17:16:43 +0200
Subject: [PATCH 1/4] Write documentation for the notetaking system

---
 rhdl-core/Cargo.toml        |   3 +
 rhdl-core/src/note_db.rs    | 305 +++++++++++++++++++++++++++++++++++-
 rhdl-core/src/types/note.rs |  21 ++-
 3 files changed, 315 insertions(+), 14 deletions(-)

diff --git a/rhdl-core/Cargo.toml b/rhdl-core/Cargo.toml
index d3656f07..f51f1300 100644
--- a/rhdl-core/Cargo.toml
+++ b/rhdl-core/Cargo.toml
@@ -23,6 +23,9 @@ syn = "2.0.38"
 tempfile = "3.8.1"
 vcd = "0.7.0"
 
+[dev-dependencies]
+rhdl = { path = "../rhdl" }
+
 [features]
 default = ["svg", "iverilog"]
 svg = ["dep:svg"]
diff --git a/rhdl-core/src/note_db.rs b/rhdl-core/src/note_db.rs
index e3f8b22d..32b99341 100644
--- a/rhdl-core/src/note_db.rs
+++ b/rhdl-core/src/note_db.rs
@@ -1,3 +1,102 @@
+//! The note database is a log designed around time series of data values (like an oscilloscope). It can be exported to a VCD file.
+//!
+//! rhdl's notetaking system is designed around a note database singleton which can be accessed using the functions provided by this module. The term _note_ refers to the value for a specific variable at a specific timestamp.
+//!
+//! First you should use the [`note_init_db`] function to initialize the global note database. Then you can use [`note`] to add values. After you are done, call [`note_take`] to get the note database and dump it to a [Value-Change Dump (VCD)](https://en.wikipedia.org/wiki/Value_change_dump) file.
+//!
+//! # Examples
+//!
+//! Dump the simulation of a synchronous module to a VCD file:
+//!
+//! ```
+//! use rhdl::{bits::bits, synchronous::{simulate, OneShot}};
+//! use rhdl_core::{note_init_db, note_take};
+//! // Reset db
+//! note_init_db();
+//!
+//! // Simulate device
+//! let inputs = vec![false, true, false, false, false, false, false, false].into_iter();
+//! let dut = OneShot::<26> { duration: bits(3) };
+//! simulate(dut, inputs).count();
+//!
+//! // Write notes to VCD file
+//! let mut vcd_file = std::fs::File::create("oneshot.vcd").unwrap();
+//! note_take().unwrap().dump_vcd(&[], &mut vcd_file).unwrap();
+//! ```
+//!
+//! Use the notetaking functions outside of a simulation:
+//!
+//! ```
+//! use rhdl_core::{note, note_init_db, note_time, note_take};
+//! // Reset db
+//! note_init_db();
+//!
+//! // Note some values
+//! note("a", false);
+//! note_time(1000);
+//! note("a", true);
+//! note_time(2000);
+//! note("a", false);
+//!
+//! // Dump the note database to a VCD file
+//! let mut vcd_file = std::fs::File::create("dump.vcd").unwrap();
+//! note_take().unwrap().dump_vcd(&[], vcd_file).unwrap();
+//! ```
+//!
+//! Usage inside the kernel of a synchronous module:
+//!
+//! ```
+//! use rhdl::{kernel, Digital};
+//! use rhdl_core::{note, Synchronous};
+//!
+//! /// Adds the input to the sum of the previous inputs every clock cycle
+//! #[derive(Copy, Clone, PartialEq, Eq, Debug, Digital, Default)]
+//! struct SumAccumulator {}
+//!
+//! impl Synchronous for SumAccumulator {
+//!     type Input = u8;
+//!     type Output = u8;
+//!     type State = u8;
+//!     type Update = sum_accumulator_update;
+//!
+//!     const INITIAL_STATE: Self::State = 0;
+//!     const UPDATE: fn(Self, Self::State, Self::Input) -> (Self::State, Self::Output) =
+//!         sum_accumulator_update;
+//! }
+//!
+//! #[kernel]
+//! pub fn sum_accumulator_update(
+//!     _params: SumAccumulator,
+//!     state: u8,
+//!     input: u8,
+//! ) -> (u8, u8) {
+//!     // Take notes in the update function
+//!     note("input", input);
+//!     note("state", state);
+//!     let output = input + state;
+//!     note("output", output);
+//!     return (output, output);
+//! }
+//!
+//! #[cfg(test)]
+//! mod tests {
+//!     use rhdl::synchronous::simulate;
+//!     use rhdl_core::{note_init_db, note_take};
+//!
+//!     use super::SumAccumulator;
+//!     #[test]
+//!     fn test_start_pulse_simulation() {
+//!         note_init_db();
+//!
+//!         let inputs = vec![4, 6, 8, 12, 3].into_iter();
+//!         let dut = SumAccumulator {};
+//!         simulate(dut, inputs).count();
+//!
+//!         let mut vcd_file = std::fs::File::create("sum_accumulator.vcd").unwrap();
+//!         note_take().unwrap().dump_vcd(&[], &mut vcd_file).unwrap();
+//!     }
+//! }
+//! ```
 use crate::types::note::Notable;
 use crate::{ClockDetails, NoteKey, NoteWriter};
 use anyhow::bail;
@@ -5,13 +104,20 @@ use std::hash::Hash;
 use std::{cell::RefCell, hash::Hasher, io::Write};
 use vcd::IdCode;
 
+/// A timestamp in picoseconds since the start of the simulation.
+type Time = u64;
+
+/// A time series of values at different times.
 struct TimeSeries<T> {
-    values: Vec<(u64, T)>,
+    /// A list of time and value pairs.
+    values: Vec<(Time, T)>,
+    /// The width of the value in bits.
     width: u8,
 }
 
 impl<T> TimeSeries<T> {
-    fn new(time: u64, value: T, width: u8) -> Self {
+    /// Create a new time series with a single value.
+    fn new(time: Time, value: T, width: u8) -> Self {
         Self {
             values: vec![(time, value)],
             width,
@@ -159,7 +265,7 @@ impl TimeSeries<Tristate> {
 }
 
 impl<T: PartialEq> TimeSeries<T> {
-    fn push(&mut self, time: u64, value: T, width: u8) {
+    fn push(&mut self, time: Time, value: T, width: u8) {
         if let Some((_last_time, last_value)) = self.values.last() {
             if *last_value == value {
                 return;
@@ -201,20 +307,49 @@ fn bits_to_vcd(x: u128, width: usize, buffer: &mut [u8]) {
     })
 }
 
+/// A log for hardware designs that is designed around time series of data values (like an oscilloscope) than a text journal of log entries.
+///
+/// It keeps track of the module that is currently being noted, the current time, and the values of all time series.
+///
+/// rhdl uses a global note database singleton to store all the notes. You can access this singleton using the functions exported by [`crate::note_db``].
+///
+/// # Example
+///
+/// Dump the note database to a VCD file:
+///
+/// ```
+/// # // Hidden, because the example assumes, you initialized the note database somewhere else
+/// # use rhdl_core::{note_init_db};
+/// # note_init_db();
+/// use rhdl_core::{note_take};
+///
+/// // Get the note database singleton
+/// let db = note_take().unwrap();
+///
+/// // Write the note database to a VCD file
+/// db.dump_vcd(&[], std::fs::File::create("dump.vcd").unwrap()).unwrap();
+/// ```
+///
+/// See [`note_db`](crate::note_db#examples) for more examples.
 #[derive(Default)]
 pub struct NoteDB {
+    /// The names for each time series of values.
+    details: fnv::FnvHashMap<String, TimeSeriesDetails>,
+    /// The picoseconds since start of the simulation.
+    time: Time,
+    /// The current path in the design hierarchy.
+    ///
+    /// The current value will be prepended to all noted keys. Can be adjusted with [`push_path`] and [`pop_path`]. The main idea is to push the current module name before noting values in that module, so that the VCD dump will have the full path to the signal.
+    path: Vec<&'static str>,
     db_bool: fnv::FnvHashMap<TimeSeriesHash, TimeSeries<bool>>,
     db_bits: fnv::FnvHashMap<TimeSeriesHash, TimeSeries<u128>>,
     db_signed: fnv::FnvHashMap<TimeSeriesHash, TimeSeries<i128>>,
     db_string: fnv::FnvHashMap<TimeSeriesHash, TimeSeries<&'static str>>,
     db_tristate: fnv::FnvHashMap<TimeSeriesHash, TimeSeries<Tristate>>,
-    details: fnv::FnvHashMap<String, TimeSeriesDetails>,
-    path: Vec<&'static str>,
-    time: u64,
 }
 
 struct Cursor {
-    next_time: Option<u64>,
+    next_time: Option<Time>,
     hash: TimeSeriesHash,
     kind: TimeSeriesKind,
     ptr: usize,
@@ -222,6 +357,7 @@ struct Cursor {
     code_as_bytes: Vec<u8>,
 }
 
+/// Represents the possible value types of a time series.
 #[derive(Copy, Clone, Debug)]
 enum TimeSeriesKind {
     Bool,
@@ -231,6 +367,7 @@ enum TimeSeriesKind {
     Tristate,
 }
 
+/// Implementation for writing notes to the [`NoteDB`].
 impl NoteWriter for NoteDB {
     fn write_bool(&mut self, key: impl NoteKey, value: bool) {
         self.note_bool(key, value);
@@ -254,9 +391,11 @@ impl NoteWriter for NoteDB {
 }
 
 impl NoteDB {
+    /// See [`note_push_path`].
     fn push_path(&mut self, name: &'static str) {
         self.path.push(name);
     }
+    /// See [`note_pop_path`].
     fn pop_path(&mut self) {
         self.path.pop();
     }
@@ -421,6 +560,34 @@ impl NoteDB {
         }
     }
 
+    /// Write the current state of this note database to a VCD dump.
+    ///
+    /// The VCD dump will contain all the values that have been noted so far.
+    ///
+    /// The `clocks` parameter can be used to add additional [`ClockDetails`] for reference.
+    ///
+    /// # Example
+    ///
+    /// Dump the current state of the note database to a VCD file:
+    ///
+    /// ```
+    /// # use rhdl_core::{note_take, note_init_db};
+    /// # note_init_db();
+    /// #
+    /// let mut vcd_file = std::fs::File::create("dump.vcd").unwrap();
+    /// note_take().unwrap().dump_vcd(&[], vcd_file).unwrap();
+    /// ```
+    ///
+    /// Dump VCD into a buffer:
+    ///
+    /// ```
+    /// # use rhdl_core::{note_take, note_init_db};
+    /// # note_init_db();
+    /// #
+    /// let mut vcd_content = vec![];
+    /// note_take().unwrap().dump_vcd(&[], &mut vcd_content).unwrap();
+    /// ```
+    // TODO: Create a `note_dump_vcd` function to make this more ergonomic.
     pub fn dump_vcd<W: Write>(&self, clocks: &[ClockDetails], w: W) -> anyhow::Result<()> {
         let mut writer = vcd::Writer::new(w);
         writer.timescale(1, vcd::TimescaleUnit::PS)?;
@@ -488,13 +655,55 @@ impl NoteDB {
 }
 
 thread_local! {
+    /// The note database singleton.
+    ///
+    /// This is where all the traces are stored when using the [`note`] function.
+    ///
+    /// Access this using the [`note_take`] function to get the database and dump it to a VCD file.
     static DB: RefCell<Option<NoteDB>> = RefCell::new(None);
 }
 
+/// Initialize/Reset the note database singleton.
+///
+/// After calling this function you can write notes using [`note`]. When you are done, you can take the note database using [`note_take`].
+///
+/// # Examples
+///
+/// Initialize the note database singleton:
+///
+/// ```
+/// use rhdl_core::{note_init_db};
+///
+/// note_init_db();
+/// ```
+///
+/// Reset the note database singleton:
+///
+/// ```
+/// use rhdl_core::{note_init_db, note};
+///
+/// note_init_db();
+///
+/// // Note some values
+/// note("a", false);
+/// note("b", 6);
+///
+/// // Reset the note database
+/// note_init_db();
+///
+/// // The note database is now empty again
+/// ```
+///
+/// See [`note_db`](crate::note_db#examples) for more examples.
 pub fn note_init_db() {
     DB.replace(Some(NoteDB::default()));
 }
 
+/// Add a path to path stack in the design hierarchy.
+///
+/// The current path stack will be prepended to all noted keys.
+///
+/// If you are implementing [`crate::Circuit`] yourself, this should be called in the [`crate::Circuit::sim`] method, before calling sim on a child circuit. Remember to call [`note_pop_path`] to remove the path from the stack after simulating the child circuits.
 pub fn note_push_path(name: &'static str) {
     DB.with(|db| {
         let mut db = db.borrow_mut();
@@ -504,6 +713,9 @@ pub fn note_push_path(name: &'static str) {
     });
 }
 
+/// Remove a path from the path stack in the design hierarchy.
+///
+/// See [`note_push_path`] for more information.
 pub fn note_pop_path() {
     DB.with(|db| {
         let mut db = db.borrow_mut();
@@ -513,7 +725,10 @@ pub fn note_pop_path() {
     });
 }
 
-pub fn note_time(time: u64) {
+/// Set the current time.
+///
+/// The time that will be used for all notes written after this call.
+pub fn note_time(time: Time) {
     DB.with(|db| {
         let mut db = db.borrow_mut();
         if let Some(db) = db.as_mut() {
@@ -522,6 +737,37 @@ pub fn note_time(time: u64) {
     });
 }
 
+/// Write a value for the key at the current time to the note database singleton.
+///
+/// You should have initialized the note database [`note_init_db`] before calling this function.
+///
+/// The current path prefix (See [`note_push_path`], and [`note_pop_path`]) will be prepended to the key.
+///
+/// # Examples
+///
+/// Note a value for `input` to the note database singleton
+///
+/// ```
+/// use rhdl_core::{note};
+///
+/// note("input", 5);
+/// ```
+///
+/// Logging in a kernel:
+///
+/// ```
+/// use rhdl::{kernel};
+/// use rhdl_core::{note, note_init_db, note_take};
+///
+/// #[kernel]
+/// fn adder(a: u8, b: u8) -> u8 {
+///     note("a", a);
+///     note("b", b);
+///     return a + b;
+/// }
+/// ```
+///
+/// See [`note_db`](crate::note_db#examples) for more examples.
 pub fn note(key: impl NoteKey, value: impl Notable) {
     DB.with(|db| {
         let mut db = db.borrow_mut();
@@ -531,6 +777,49 @@ pub fn note(key: impl NoteKey, value: impl Notable) {
     });
 }
 
+/// Take the note database singleton.
+///
+/// This will leave the database singleton unset, you need to call [`note_init_db`] after this before noting more values.
+///
+/// # Examples
+///
+/// Take the note database singleton and dump it to a VCD file.
+///
+/// ```
+/// # // Hidden, because the example assumes, you initialized the note database somewhere else
+/// # use rhdl_core::{note_init_db};
+/// # note_init_db();
+/// use rhdl_core::{note_take};
+///
+/// let mut vcd_file = std::fs::File::create("dump.vcd").unwrap();
+/// note_take().unwrap().dump_vcd(&[], vcd_file).unwrap();
+/// ```
+///
+/// Remember to call [`note_init_db`] again after taking the database.
+///
+/// ```should_panic
+/// use rhdl_core::{note, note_init_db, note_time, note_take};
+///
+/// // Dump the note database to a VCD file
+/// let mut vcd_file = std::fs::File::create("dump.vcd").unwrap();
+/// note_take().unwrap().dump_vcd(&[], vcd_file).unwrap();
+///
+/// // Forget to call note_init_db again
+/// // note_init_db();
+///
+/// // Try to note some values
+/// note("a", false);
+/// note_time(1000);
+/// note("a", true);
+/// note_time(2000);
+/// note("a", false);
+///
+/// // Panic, because the note database is not initialized
+/// let mut vcd_file = std::fs::File::create("dump.vcd").unwrap();
+/// note_take().unwrap().dump_vcd(&[], vcd_file).unwrap();
+/// ```
+///
+/// See [`note_db`](crate::note_db#examples) for more examples.
 pub fn note_take() -> Option<NoteDB> {
     DB.with(|db| db.borrow_mut().take())
 }
diff --git a/rhdl-core/src/types/note.rs b/rhdl-core/src/types/note.rs
index a7c69702..77f4d36d 100644
--- a/rhdl-core/src/types/note.rs
+++ b/rhdl-core/src/types/note.rs
@@ -1,11 +1,9 @@
-// Essentially like a log for hardware designs that is designed more
-// around time series of data values (like an oscilloscope) than a
-// text journal of log entries.  The use of the name `note` is to
-// suggest that it is _like_ a log, but not quite the same thing.
-// The user can _also_ use regular log stuff if they want.
-
+//! Traits used for logging values for debugging.
+//!
+//! See the [`crate::note_db`] module for more information on the logging system.
 use std::hash::Hash;
 
+/// Provides methods for logging key value pairs at the current simulation time.
 pub trait NoteWriter {
     fn write_bool(&mut self, key: impl NoteKey, value: bool);
     fn write_bits(&mut self, key: impl NoteKey, value: u128, size: u8);
@@ -32,22 +30,28 @@ impl<T: NoteWriter> NoteWriter for &mut T {
     }
 }
 
+/// A value that can be used as a signal name in the vcd dump.
+///
+/// Used by the [`note`](crate::note) function.
 pub trait NoteKey: Clone + Copy + Hash {
     fn as_string(&self) -> String;
 }
 
+/// A static string be used as is
 impl NoteKey for &'static str {
     fn as_string(&self) -> String {
         self.to_string()
     }
 }
 
+/// Numbers are converted to strings
 impl NoteKey for usize {
     fn as_string(&self) -> String {
         format!("{}", self)
     }
 }
 
+/// String arrays are be joined with `::`
 impl NoteKey for &[&'static str] {
     fn as_string(&self) -> String {
         self.iter()
@@ -57,13 +61,18 @@ impl NoteKey for &[&'static str] {
     }
 }
 
+/// Tuples of NoteKeys are joined with `::`
 impl<T: NoteKey, U: NoteKey> NoteKey for (T, U) {
     fn as_string(&self) -> String {
         format!("{}::{}", self.0.as_string(), self.1.as_string())
     }
 }
 
+/// A value that can be logged to a [`NoteWriter`].
+///
+/// Used by the [`note`](crate::note) function.
 pub trait Notable {
+    /// Write this value to the note writer. The key is used to identify the value.
     fn note(&self, key: impl NoteKey, writer: impl NoteWriter);
 }
 

From 1d8492ac88e5cca1e7be265bcb5a6b444c865cb2 Mon Sep 17 00:00:00 2001
From: Zebreus <lennart@zebre.us>
Date: Sat, 25 May 2024 18:37:43 +0200
Subject: [PATCH 2/4] Adjust note database singleton to not require explicit
 initialization

---
 rhdl-core/src/note_db.rs   | 126 +++++++++++++------------------------
 rhdl-x/src/main.rs         |   6 +-
 rhdl-x/src/push_pull.rs    |   4 +-
 rhdl/src/synchronous.rs    |   8 +--
 rhdl/src/tests.rs          |   6 +-
 rhdl/tests/complex_enum.rs |   2 +-
 6 files changed, 58 insertions(+), 94 deletions(-)

diff --git a/rhdl-core/src/note_db.rs b/rhdl-core/src/note_db.rs
index 32b99341..4633499d 100644
--- a/rhdl-core/src/note_db.rs
+++ b/rhdl-core/src/note_db.rs
@@ -2,7 +2,7 @@
 //!
 //! rhdl's notetaking system is designed around a note database singleton which can be accessed using the functions provided by this module. The term _note_ refers to the value for a specific variable at a specific timestamp.
 //!
-//! First you should use the [`note_init_db`] function to initialize the global note database. Then you can use [`note`] to add values. After you are done, call [`note_take`] to get the note database and dump it to a [Value-Change Dump (VCD)](https://en.wikipedia.org/wiki/Value_change_dump) file.
+//! Use [`note`] to log values to the note database. After you are done, call [`note_take`] to get the note database and dump it to a [Value-Change Dump (VCD)](https://en.wikipedia.org/wiki/Value_change_dump) file.
 //!
 //! # Examples
 //!
@@ -11,8 +11,6 @@
 //! ```
 //! use rhdl::{bits::bits, synchronous::{simulate, OneShot}};
 //! use rhdl_core::{note_init_db, note_take};
-//! // Reset db
-//! note_init_db();
 //!
 //! // Simulate device
 //! let inputs = vec![false, true, false, false, false, false, false, false].into_iter();
@@ -21,7 +19,7 @@
 //!
 //! // Write notes to VCD file
 //! let mut vcd_file = std::fs::File::create("oneshot.vcd").unwrap();
-//! note_take().unwrap().dump_vcd(&[], &mut vcd_file).unwrap();
+//! note_take().dump_vcd(&[], &mut vcd_file).unwrap();
 //! ```
 //!
 //! Use the notetaking functions outside of a simulation:
@@ -40,7 +38,7 @@
 //!
 //! // Dump the note database to a VCD file
 //! let mut vcd_file = std::fs::File::create("dump.vcd").unwrap();
-//! note_take().unwrap().dump_vcd(&[], vcd_file).unwrap();
+//! note_take().dump_vcd(&[], vcd_file).unwrap();
 //! ```
 //!
 //! Usage inside the kernel of a synchronous module:
@@ -81,19 +79,17 @@
 //! #[cfg(test)]
 //! mod tests {
 //!     use rhdl::synchronous::simulate;
-//!     use rhdl_core::{note_init_db, note_take};
+//!     use rhdl_core::note_take;
 //!
 //!     use super::SumAccumulator;
 //!     #[test]
 //!     fn test_start_pulse_simulation() {
-//!         note_init_db();
-//!
 //!         let inputs = vec![4, 6, 8, 12, 3].into_iter();
 //!         let dut = SumAccumulator {};
 //!         simulate(dut, inputs).count();
 //!
 //!         let mut vcd_file = std::fs::File::create("sum_accumulator.vcd").unwrap();
-//!         note_take().unwrap().dump_vcd(&[], &mut vcd_file).unwrap();
+//!         note_take().dump_vcd(&[], &mut vcd_file).unwrap();
 //!     }
 //! }
 //! ```
@@ -318,13 +314,14 @@ fn bits_to_vcd(x: u128, width: usize, buffer: &mut [u8]) {
 /// Dump the note database to a VCD file:
 ///
 /// ```
-/// # // Hidden, because the example assumes, you initialized the note database somewhere else
-/// # use rhdl_core::{note_init_db};
-/// # note_init_db();
-/// use rhdl_core::{note_take};
+/// use rhdl_core::{note_take, note};
+///
+/// // Write some notes
+/// note("a", false);
+/// note("b", 42);
 ///
 /// // Get the note database singleton
-/// let db = note_take().unwrap();
+/// let db = note_take();
 ///
 /// // Write the note database to a VCD file
 /// db.dump_vcd(&[], std::fs::File::create("dump.vcd").unwrap()).unwrap();
@@ -571,21 +568,19 @@ impl NoteDB {
     /// Dump the current state of the note database to a VCD file:
     ///
     /// ```
-    /// # use rhdl_core::{note_take, note_init_db};
-    /// # note_init_db();
-    /// #
+    /// use rhdl_core::{note_take};
+    ///
     /// let mut vcd_file = std::fs::File::create("dump.vcd").unwrap();
-    /// note_take().unwrap().dump_vcd(&[], vcd_file).unwrap();
+    /// note_take().dump_vcd(&[], vcd_file).unwrap();
     /// ```
     ///
     /// Dump VCD into a buffer:
     ///
     /// ```
-    /// # use rhdl_core::{note_take, note_init_db};
-    /// # note_init_db();
-    /// #
+    /// use rhdl_core::{note_take};
+    ///
     /// let mut vcd_content = vec![];
-    /// note_take().unwrap().dump_vcd(&[], &mut vcd_content).unwrap();
+    /// note_take().dump_vcd(&[], &mut vcd_content).unwrap();
     /// ```
     // TODO: Create a `note_dump_vcd` function to make this more ergonomic.
     pub fn dump_vcd<W: Write>(&self, clocks: &[ClockDetails], w: W) -> anyhow::Result<()> {
@@ -657,33 +652,21 @@ impl NoteDB {
 thread_local! {
     /// The note database singleton.
     ///
-    /// This is where all the traces are stored when using the [`note`] function.
+    /// It will get initialized when you first use any of the [`note`] functions.
     ///
-    /// Access this using the [`note_take`] function to get the database and dump it to a VCD file.
-    static DB: RefCell<Option<NoteDB>> = RefCell::new(None);
+    /// Use the [`note_take`] function to get the database and dump it to a VCD file.
+    static DB: RefCell<NoteDB> = RefCell::new(NoteDB::default());
 }
 
-/// Initialize/Reset the note database singleton.
-///
-/// After calling this function you can write notes using [`note`]. When you are done, you can take the note database using [`note_take`].
+/// Reset the note database singleton to an empty state.
 ///
 /// # Examples
 ///
-/// Initialize the note database singleton:
-///
-/// ```
-/// use rhdl_core::{note_init_db};
-///
-/// note_init_db();
-/// ```
-///
 /// Reset the note database singleton:
 ///
 /// ```
 /// use rhdl_core::{note_init_db, note};
 ///
-/// note_init_db();
-///
 /// // Note some values
 /// note("a", false);
 /// note("b", 6);
@@ -696,7 +679,7 @@ thread_local! {
 ///
 /// See [`note_db`](crate::note_db#examples) for more examples.
 pub fn note_init_db() {
-    DB.replace(Some(NoteDB::default()));
+    DB.replace(NoteDB::default());
 }
 
 /// Add a path to path stack in the design hierarchy.
@@ -707,9 +690,7 @@ pub fn note_init_db() {
 pub fn note_push_path(name: &'static str) {
     DB.with(|db| {
         let mut db = db.borrow_mut();
-        if let Some(db) = db.as_mut() {
-            db.push_path(name)
-        }
+        db.push_path(name);
     });
 }
 
@@ -719,9 +700,7 @@ pub fn note_push_path(name: &'static str) {
 pub fn note_pop_path() {
     DB.with(|db| {
         let mut db = db.borrow_mut();
-        if let Some(db) = db.as_mut() {
-            db.pop_path()
-        }
+        db.pop_path();
     });
 }
 
@@ -731,16 +710,12 @@ pub fn note_pop_path() {
 pub fn note_time(time: Time) {
     DB.with(|db| {
         let mut db = db.borrow_mut();
-        if let Some(db) = db.as_mut() {
-            db.time = time
-        }
+        db.time = time;
     });
 }
 
 /// Write a value for the key at the current time to the note database singleton.
 ///
-/// You should have initialized the note database [`note_init_db`] before calling this function.
-///
 /// The current path prefix (See [`note_push_path`], and [`note_pop_path`]) will be prepended to the key.
 ///
 /// # Examples
@@ -756,8 +731,8 @@ pub fn note_time(time: Time) {
 /// Logging in a kernel:
 ///
 /// ```
-/// use rhdl::{kernel};
-/// use rhdl_core::{note, note_init_db, note_take};
+/// use rhdl::kernel;
+/// use rhdl_core::note;
 ///
 /// #[kernel]
 /// fn adder(a: u8, b: u8) -> u8 {
@@ -770,58 +745,47 @@ pub fn note_time(time: Time) {
 /// See [`note_db`](crate::note_db#examples) for more examples.
 pub fn note(key: impl NoteKey, value: impl Notable) {
     DB.with(|db| {
-        let mut db = db.borrow_mut();
-        if let Some(db) = db.as_mut() {
-            value.note(key, db)
-        }
+        let db: &mut NoteDB = &mut db.borrow_mut();
+        value.note(key, db);
     });
 }
 
 /// Take the note database singleton.
 ///
-/// This will leave the database singleton unset, you need to call [`note_init_db`] after this before noting more values.
+/// This will return the current note database and replace it with a new empty note database.
 ///
 /// # Examples
 ///
 /// Take the note database singleton and dump it to a VCD file.
 ///
 /// ```
-/// # // Hidden, because the example assumes, you initialized the note database somewhere else
-/// # use rhdl_core::{note_init_db};
-/// # note_init_db();
 /// use rhdl_core::{note_take};
 ///
 /// let mut vcd_file = std::fs::File::create("dump.vcd").unwrap();
-/// note_take().unwrap().dump_vcd(&[], vcd_file).unwrap();
+/// note_take().dump_vcd(&[], vcd_file).unwrap();
 /// ```
 ///
-/// Remember to call [`note_init_db`] again after taking the database.
+/// After calling note take, the note database will be empty:
 ///
-/// ```should_panic
+/// ```
 /// use rhdl_core::{note, note_init_db, note_time, note_take};
 ///
+/// // Note some values
+/// note("a", false);
+/// note("b", 5);
+///
 /// // Dump the note database to a VCD file
 /// let mut vcd_file = std::fs::File::create("dump.vcd").unwrap();
-/// note_take().unwrap().dump_vcd(&[], vcd_file).unwrap();
-///
-/// // Forget to call note_init_db again
-/// // note_init_db();
-///
-/// // Try to note some values
-/// note("a", false);
-/// note_time(1000);
-/// note("a", true);
-/// note_time(2000);
-/// note("a", false);
+/// note_take().dump_vcd(&[], vcd_file).unwrap();
 ///
-/// // Panic, because the note database is not initialized
+/// // This will create an empty VCD file
 /// let mut vcd_file = std::fs::File::create("dump.vcd").unwrap();
-/// note_take().unwrap().dump_vcd(&[], vcd_file).unwrap();
+/// note_take().dump_vcd(&[], vcd_file).unwrap();
 /// ```
 ///
 /// See [`note_db`](crate::note_db#examples) for more examples.
-pub fn note_take() -> Option<NoteDB> {
-    DB.with(|db| db.borrow_mut().take())
+pub fn note_take() -> NoteDB {
+    DB.replace(NoteDB::default())
 }
 
 #[cfg(test)]
@@ -843,7 +807,7 @@ mod tests {
             note("b", i % 2 == 1);
         }
         let mut vcd = vec![];
-        let db = note_take().unwrap();
+        let db = note_take();
         let clock = ClockDetails::new("clk", 5, 0, false);
         db.dump_vcd(&[clock], &mut vcd).unwrap();
         std::fs::write("test.vcd", vcd).unwrap();
@@ -996,7 +960,7 @@ mod tests {
 
         let clock = ClockDetails::new("clk", 100, 0, false);
         let mut vcd = vec![];
-        let db = note_take().unwrap();
+        let db = note_take();
         db.dump_vcd(&[clock], &mut vcd).unwrap();
         std::fs::write("test_enum.vcd", vcd).unwrap();
     }
@@ -1015,7 +979,7 @@ mod tests {
         }
         let mut vcd = vec![];
         let clock = ClockDetails::new("clk", 500, 0, false);
-        let db = note_take().unwrap();
+        let db = note_take();
         db.dump_vcd(&[clock], &mut vcd).unwrap();
         std::fs::write("test_nested_paths.vcd", vcd).unwrap();
     }
diff --git a/rhdl-x/src/main.rs b/rhdl-x/src/main.rs
index 2a4ff2f2..d1448ad2 100644
--- a/rhdl-x/src/main.rs
+++ b/rhdl-x/src/main.rs
@@ -97,7 +97,7 @@ fn test_dff() {
         let output = dff.sim(input, &mut state, &mut io);
         note("output", output);
     }
-    let db = note_take().unwrap();
+    let db = note_take();
     let dff = std::fs::File::create("dff.vcd").unwrap();
     db.dump_vcd(&[], dff).unwrap();
 }
@@ -120,7 +120,7 @@ fn test_strobe() {
         let output = strobe.sim(input, &mut state, &mut io);
         note("output", output);
     }
-    let db = note_take().unwrap();
+    let db = note_take();
     let strobe = std::fs::File::create("strobe.vcd").unwrap();
     db.dump_vcd(&[], strobe).unwrap();
 }
@@ -179,7 +179,7 @@ fn main() {
         let output = counter.sim(input, &mut state, &mut io);
         note("output", output);
     }
-    let db = note_take().unwrap();
+    let db = note_take();
     let dff = std::fs::File::create("counter.vcd").unwrap();
     db.dump_vcd(&[], dff).unwrap();
 }
diff --git a/rhdl-x/src/push_pull.rs b/rhdl-x/src/push_pull.rs
index b858c844..b79cc295 100644
--- a/rhdl-x/src/push_pull.rs
+++ b/rhdl-x/src/push_pull.rs
@@ -439,7 +439,7 @@ fn test_simulate_push() {
         note("bus", io);
     }
     note_pop_path();
-    let db = note_take().unwrap();
+    let db = note_take();
     let push = std::fs::File::create("push.vcd").unwrap();
     db.dump_vcd(&[], push).unwrap();
 }
@@ -619,7 +619,7 @@ fn test_simulate_push_pair() {
         }
         note("bus", io);
     }
-    let db = note_take().unwrap();
+    let db = note_take();
     let push = std::fs::File::create("push_pair.vcd").unwrap();
     db.dump_vcd(&[], push).unwrap();
 }
diff --git a/rhdl/src/synchronous.rs b/rhdl/src/synchronous.rs
index 702c8125..0e35fe72 100644
--- a/rhdl/src/synchronous.rs
+++ b/rhdl/src/synchronous.rs
@@ -283,7 +283,7 @@ fn test_strobe_simulation() {
     let outputs = simulate(strobe, enable).filter(|x| *x).count();
     eprintln!("outputs: {}, elapsed {:?}", outputs, now.elapsed());
     let mut vcd_file = std::fs::File::create("strobe.vcd").unwrap();
-    note_take().unwrap().dump_vcd(&[], &mut vcd_file).unwrap();
+    note_take().dump_vcd(&[], &mut vcd_file).unwrap();
 }
 
 #[test]
@@ -294,7 +294,7 @@ fn test_start_pulse_simulation() {
     let outputs = simulate(pulse, input).filter(|x| *x).count();
     assert_eq!(outputs, 1);
     let mut vcd_file = std::fs::File::create("start_pulse.vcd").unwrap();
-    note_take().unwrap().dump_vcd(&[], &mut vcd_file).unwrap();
+    note_take().dump_vcd(&[], &mut vcd_file).unwrap();
 }
 
 #[test]
@@ -307,7 +307,7 @@ fn test_one_shot_simulation() {
     note_init_db();
     let outputs = simulate(one_shot, input).filter(|x| *x).count();
     let mut vcd_file = std::fs::File::create("one_shot.vcd").unwrap();
-    note_take().unwrap().dump_vcd(&[], &mut vcd_file).unwrap();
+    note_take().dump_vcd(&[], &mut vcd_file).unwrap();
 }
 
 #[test]
@@ -320,7 +320,7 @@ fn test_pulser_simulation() {
     note_init_db();
     let outputs = simulate(pulser, input).filter(|x| *x).count();
     let mut vcd_file = std::fs::File::create("pulser.vcd").unwrap();
-    note_take().unwrap().dump_vcd(&[], &mut vcd_file).unwrap();
+    note_take().dump_vcd(&[], &mut vcd_file).unwrap();
 }
 
 #[test]
diff --git a/rhdl/src/tests.rs b/rhdl/src/tests.rs
index f76d5aba..615c7c34 100644
--- a/rhdl/src/tests.rs
+++ b/rhdl/src/tests.rs
@@ -46,7 +46,7 @@ fn test_vcd_enum() {
     note_time(8_000);
     note("enum", Enum::None);
     let mut vcd_file = std::fs::File::create("test_enum.vcd").unwrap();
-    note_take().unwrap().dump_vcd(&[], &mut vcd_file).unwrap();
+    note_take().dump_vcd(&[], &mut vcd_file).unwrap();
 }
 
 #[test]
@@ -73,7 +73,7 @@ fn test_vcd_basic() {
     note_time(2_000);
     note("simple", simple);
     let mut vcd_file = std::fs::File::create("test.vcd").unwrap();
-    note_take().unwrap().dump_vcd(&[], &mut vcd_file).unwrap();
+    note_take().dump_vcd(&[], &mut vcd_file).unwrap();
 }
 
 #[test]
@@ -199,7 +199,7 @@ fn test_derive_digital_complex_enum() {
     note_time(3_000);
     note("test", foo_1);
     let mut vcd_file = std::fs::File::create("test_enum.vcd").unwrap();
-    note_take().unwrap().dump_vcd(&[], &mut vcd_file).unwrap();
+    note_take().dump_vcd(&[], &mut vcd_file).unwrap();
 }
 
 #[test]
diff --git a/rhdl/tests/complex_enum.rs b/rhdl/tests/complex_enum.rs
index e21299a6..7650b393 100644
--- a/rhdl/tests/complex_enum.rs
+++ b/rhdl/tests/complex_enum.rs
@@ -241,5 +241,5 @@ fn test_vcd_generation() {
     note_time(6_000);
     note("packet", Packet::State(State::Running));
     let mut vcd_file = std::fs::File::create("packet.vcd").unwrap();
-    note_take().unwrap().dump_vcd(&[], vcd_file).unwrap();
+    note_take().dump_vcd(&[], vcd_file).unwrap();
 }

From e377d8e6f98860fdd364a3d4ce2111e4f45aeefb Mon Sep 17 00:00:00 2001
From: Zebreus <lennart@zebre.us>
Date: Sat, 25 May 2024 19:28:57 +0200
Subject: [PATCH 3/4] Refactor dump_vcd to note_take_vcd

---
 rhdl-core/src/lib.rs       |   3 +-
 rhdl-core/src/note_db.rs   | 119 +++++++++++++------------------------
 rhdl-x/src/main.rs         |  11 ++--
 rhdl-x/src/push_pull.rs    |   8 +--
 rhdl/src/synchronous.rs    |  10 ++--
 rhdl/src/tests.rs          |   8 +--
 rhdl/tests/complex_enum.rs |   4 +-
 7 files changed, 60 insertions(+), 103 deletions(-)

diff --git a/rhdl-core/src/lib.rs b/rhdl-core/src/lib.rs
index 5b6f65e5..c50eb64e 100644
--- a/rhdl-core/src/lib.rs
+++ b/rhdl-core/src/lib.rs
@@ -47,9 +47,8 @@ pub use note_db::note;
 pub use note_db::note_init_db;
 pub use note_db::note_pop_path;
 pub use note_db::note_push_path;
-pub use note_db::note_take;
+pub use note_db::note_take_vcd;
 pub use note_db::note_time;
-pub use note_db::NoteDB;
 pub use schematic::components::BlackBoxComponent;
 pub use schematic::components::BlackBoxTrait;
 pub use schematic::constraints::constraint_input_synchronous;
diff --git a/rhdl-core/src/note_db.rs b/rhdl-core/src/note_db.rs
index 4633499d..1218f8ca 100644
--- a/rhdl-core/src/note_db.rs
+++ b/rhdl-core/src/note_db.rs
@@ -1,8 +1,8 @@
 //! The note database is a log designed around time series of data values (like an oscilloscope). It can be exported to a VCD file.
 //!
-//! rhdl's notetaking system is designed around a note database singleton which can be accessed using the functions provided by this module. The term _note_ refers to the value for a specific variable at a specific timestamp.
+//! rhdl uses a global note database singleton to manage all the logged notes. You can access the singleton by using the functions provided by this module. The term _note_ refers to the value for a specific variable at a specific timestamp.
 //!
-//! Use [`note`] to log values to the note database. After you are done, call [`note_take`] to get the note database and dump it to a [Value-Change Dump (VCD)](https://en.wikipedia.org/wiki/Value_change_dump) file.
+//! Use [`note`] to log values to the note database. After you are done, call [`note_take_vcd`] to dump the note database to a [Value-Change Dump (VCD)](https://en.wikipedia.org/wiki/Value_change_dump) file and reset it.
 //!
 //! # Examples
 //!
@@ -10,7 +10,7 @@
 //!
 //! ```
 //! use rhdl::{bits::bits, synchronous::{simulate, OneShot}};
-//! use rhdl_core::{note_init_db, note_take};
+//! use rhdl_core::{note_init_db, note_take_vcd};
 //!
 //! // Simulate device
 //! let inputs = vec![false, true, false, false, false, false, false, false].into_iter();
@@ -19,26 +19,26 @@
 //!
 //! // Write notes to VCD file
 //! let mut vcd_file = std::fs::File::create("oneshot.vcd").unwrap();
-//! note_take().dump_vcd(&[], &mut vcd_file).unwrap();
+//! note_take_vcd(&[], &mut vcd_file).unwrap();
 //! ```
 //!
 //! Use the notetaking functions outside of a simulation:
 //!
 //! ```
-//! use rhdl_core::{note, note_init_db, note_time, note_take};
+//! use rhdl_core::{note, note_init_db, note_time, note_take_vcd};
 //! // Reset db
 //! note_init_db();
 //!
 //! // Note some values
 //! note("a", false);
+//! note("b", 42);
 //! note_time(1000);
 //! note("a", true);
-//! note_time(2000);
-//! note("a", false);
+//! note("b", 47);
 //!
 //! // Dump the note database to a VCD file
 //! let mut vcd_file = std::fs::File::create("dump.vcd").unwrap();
-//! note_take().dump_vcd(&[], vcd_file).unwrap();
+//! note_take_vcd(&[], vcd_file).unwrap();
 //! ```
 //!
 //! Usage inside the kernel of a synchronous module:
@@ -79,7 +79,7 @@
 //! #[cfg(test)]
 //! mod tests {
 //!     use rhdl::synchronous::simulate;
-//!     use rhdl_core::note_take;
+//!     use rhdl_core::note_take_vcd;
 //!
 //!     use super::SumAccumulator;
 //!     #[test]
@@ -89,7 +89,7 @@
 //!         simulate(dut, inputs).count();
 //!
 //!         let mut vcd_file = std::fs::File::create("sum_accumulator.vcd").unwrap();
-//!         note_take().dump_vcd(&[], &mut vcd_file).unwrap();
+//!         note_take_vcd(&[], &mut vcd_file).unwrap();
 //!     }
 //! }
 //! ```
@@ -308,28 +308,8 @@ fn bits_to_vcd(x: u128, width: usize, buffer: &mut [u8]) {
 /// It keeps track of the module that is currently being noted, the current time, and the values of all time series.
 ///
 /// rhdl uses a global note database singleton to store all the notes. You can access this singleton using the functions exported by [`crate::note_db``].
-///
-/// # Example
-///
-/// Dump the note database to a VCD file:
-///
-/// ```
-/// use rhdl_core::{note_take, note};
-///
-/// // Write some notes
-/// note("a", false);
-/// note("b", 42);
-///
-/// // Get the note database singleton
-/// let db = note_take();
-///
-/// // Write the note database to a VCD file
-/// db.dump_vcd(&[], std::fs::File::create("dump.vcd").unwrap()).unwrap();
-/// ```
-///
-/// See [`note_db`](crate::note_db#examples) for more examples.
 #[derive(Default)]
-pub struct NoteDB {
+struct NoteDB {
     /// The names for each time series of values.
     details: fnv::FnvHashMap<String, TimeSeriesDetails>,
     /// The picoseconds since start of the simulation.
@@ -557,33 +537,8 @@ impl NoteDB {
         }
     }
 
-    /// Write the current state of this note database to a VCD dump.
-    ///
-    /// The VCD dump will contain all the values that have been noted so far.
-    ///
-    /// The `clocks` parameter can be used to add additional [`ClockDetails`] for reference.
-    ///
-    /// # Example
-    ///
-    /// Dump the current state of the note database to a VCD file:
-    ///
-    /// ```
-    /// use rhdl_core::{note_take};
-    ///
-    /// let mut vcd_file = std::fs::File::create("dump.vcd").unwrap();
-    /// note_take().dump_vcd(&[], vcd_file).unwrap();
-    /// ```
-    ///
-    /// Dump VCD into a buffer:
-    ///
-    /// ```
-    /// use rhdl_core::{note_take};
-    ///
-    /// let mut vcd_content = vec![];
-    /// note_take().dump_vcd(&[], &mut vcd_content).unwrap();
-    /// ```
-    // TODO: Create a `note_dump_vcd` function to make this more ergonomic.
-    pub fn dump_vcd<W: Write>(&self, clocks: &[ClockDetails], w: W) -> anyhow::Result<()> {
+    /// See [`note_take_vcd`].
+    fn dump_vcd<W: Write>(&self, clocks: &[ClockDetails], w: W) -> anyhow::Result<()> {
         let mut writer = vcd::Writer::new(w);
         writer.timescale(1, vcd::TimescaleUnit::PS)?;
         writer.add_module("top")?;
@@ -654,7 +609,7 @@ thread_local! {
     ///
     /// It will get initialized when you first use any of the [`note`] functions.
     ///
-    /// Use the [`note_take`] function to get the database and dump it to a VCD file.
+    /// Use the [`note_take_vcd`] function to get the database and dump it to a VCD file.
     static DB: RefCell<NoteDB> = RefCell::new(NoteDB::default());
 }
 
@@ -750,42 +705,53 @@ pub fn note(key: impl NoteKey, value: impl Notable) {
     });
 }
 
-/// Take the note database singleton.
+/// Take and dump the note database singleton to a VCD file.
 ///
-/// This will return the current note database and replace it with a new empty note database.
+/// This will dump the note database to a VCD file and replace it with a new empty note database. The VCD dump will contain all the values that have been noted since the last [`note_take_vcd`] or [`note_init_db`].
 ///
+/// The `clocks` parameter can be used to add additional [`ClockDetails`] for reference.
 /// # Examples
 ///
-/// Take the note database singleton and dump it to a VCD file.
+/// Dump the current note database to a VCD file:
 ///
 /// ```
-/// use rhdl_core::{note_take};
+/// use rhdl_core::{note_take_vcd};
 ///
 /// let mut vcd_file = std::fs::File::create("dump.vcd").unwrap();
-/// note_take().dump_vcd(&[], vcd_file).unwrap();
+/// note_take_vcd(&[], vcd_file).unwrap();
+/// ```
+///
+/// Dump VCD into a buffer:
+///
+/// ```
+/// use rhdl_core::{note_take_vcd};
+///
+/// let mut vcd_content = vec![];
+/// note_take_vcd(&[], &mut vcd_content).unwrap();
 /// ```
 ///
-/// After calling note take, the note database will be empty:
+/// After calling `note_take_vcd`, the note database will be empty:
 ///
 /// ```
-/// use rhdl_core::{note, note_init_db, note_time, note_take};
+/// use rhdl_core::{note, note_init_db, note_time, note_take_vcd};
 ///
 /// // Note some values
 /// note("a", false);
 /// note("b", 5);
 ///
-/// // Dump the note database to a VCD file
+/// // This will create a VCD file with the notes
 /// let mut vcd_file = std::fs::File::create("dump.vcd").unwrap();
-/// note_take().dump_vcd(&[], vcd_file).unwrap();
+/// note_take_vcd(&[], vcd_file).unwrap();
 ///
-/// // This will create an empty VCD file
+/// // This will now create an empty VCD file
 /// let mut vcd_file = std::fs::File::create("dump.vcd").unwrap();
-/// note_take().dump_vcd(&[], vcd_file).unwrap();
+/// note_take_vcd(&[], vcd_file).unwrap();
 /// ```
 ///
 /// See [`note_db`](crate::note_db#examples) for more examples.
-pub fn note_take() -> NoteDB {
-    DB.replace(NoteDB::default())
+pub fn note_take_vcd<W: Write>(clocks: &[ClockDetails], writer: W) -> anyhow::Result<()> {
+    let db = DB.take();
+    db.dump_vcd(clocks, writer)
 }
 
 #[cfg(test)]
@@ -807,9 +773,8 @@ mod tests {
             note("b", i % 2 == 1);
         }
         let mut vcd = vec![];
-        let db = note_take();
         let clock = ClockDetails::new("clk", 5, 0, false);
-        db.dump_vcd(&[clock], &mut vcd).unwrap();
+        note_take_vcd(&[clock], &mut vcd).unwrap();
         std::fs::write("test.vcd", vcd).unwrap();
     }
 
@@ -960,8 +925,7 @@ mod tests {
 
         let clock = ClockDetails::new("clk", 100, 0, false);
         let mut vcd = vec![];
-        let db = note_take();
-        db.dump_vcd(&[clock], &mut vcd).unwrap();
+        note_take_vcd(&[clock], &mut vcd).unwrap();
         std::fs::write("test_enum.vcd", vcd).unwrap();
     }
 
@@ -979,8 +943,7 @@ mod tests {
         }
         let mut vcd = vec![];
         let clock = ClockDetails::new("clk", 500, 0, false);
-        let db = note_take();
-        db.dump_vcd(&[clock], &mut vcd).unwrap();
+        note_take_vcd(&[clock], &mut vcd).unwrap();
         std::fs::write("test_nested_paths.vcd", vcd).unwrap();
     }
 }
diff --git a/rhdl-x/src/main.rs b/rhdl-x/src/main.rs
index d1448ad2..e26b1f7e 100644
--- a/rhdl-x/src/main.rs
+++ b/rhdl-x/src/main.rs
@@ -12,7 +12,7 @@ use rhdl_core::note_db::note_time;
 use rhdl_core::note_init_db;
 use rhdl_core::note_pop_path;
 use rhdl_core::note_push_path;
-use rhdl_core::note_take;
+use rhdl_core::note_take_vcd;
 use rhdl_core::Circuit;
 use rhdl_core::DigitalFn;
 use rhdl_core::HDLKind;
@@ -97,9 +97,8 @@ fn test_dff() {
         let output = dff.sim(input, &mut state, &mut io);
         note("output", output);
     }
-    let db = note_take();
     let dff = std::fs::File::create("dff.vcd").unwrap();
-    db.dump_vcd(&[], dff).unwrap();
+    note_take_vcd(&[], dff).unwrap();
 }
 
 #[test]
@@ -120,9 +119,8 @@ fn test_strobe() {
         let output = strobe.sim(input, &mut state, &mut io);
         note("output", output);
     }
-    let db = note_take();
     let strobe = std::fs::File::create("strobe.vcd").unwrap();
-    db.dump_vcd(&[], strobe).unwrap();
+    note_take_vcd(&[], strobe).unwrap();
 }
 
 #[test]
@@ -179,9 +177,8 @@ fn main() {
         let output = counter.sim(input, &mut state, &mut io);
         note("output", output);
     }
-    let db = note_take();
     let dff = std::fs::File::create("counter.vcd").unwrap();
-    db.dump_vcd(&[], dff).unwrap();
+    note_take_vcd(&[], dff).unwrap();
 }
 
 #[test]
diff --git a/rhdl-x/src/push_pull.rs b/rhdl-x/src/push_pull.rs
index b79cc295..5e79fc1d 100644
--- a/rhdl-x/src/push_pull.rs
+++ b/rhdl-x/src/push_pull.rs
@@ -6,7 +6,7 @@ use rhdl_core::note;
 use rhdl_core::note_init_db;
 use rhdl_core::note_pop_path;
 use rhdl_core::note_push_path;
-use rhdl_core::note_take;
+use rhdl_core::note_take_vcd;
 use rhdl_core::note_time;
 use rhdl_core::root_descriptor;
 use rhdl_core::root_hdl;
@@ -439,9 +439,8 @@ fn test_simulate_push() {
         note("bus", io);
     }
     note_pop_path();
-    let db = note_take();
     let push = std::fs::File::create("push.vcd").unwrap();
-    db.dump_vcd(&[], push).unwrap();
+    note_take_vcd(&[], push).unwrap();
 }
 
 /*
@@ -619,9 +618,8 @@ fn test_simulate_push_pair() {
         }
         note("bus", io);
     }
-    let db = note_take();
     let push = std::fs::File::create("push_pair.vcd").unwrap();
-    db.dump_vcd(&[], push).unwrap();
+    note_take_vcd(&[], push).unwrap();
 }
 
 pub fn fold_zbus(buf: &mut PushPairZ) {
diff --git a/rhdl/src/synchronous.rs b/rhdl/src/synchronous.rs
index 0e35fe72..7914cc16 100644
--- a/rhdl/src/synchronous.rs
+++ b/rhdl/src/synchronous.rs
@@ -16,7 +16,7 @@ use rhdl_bits::{bits, Bits};
 use rhdl_core::ast::ast_impl::KernelFn;
 //use rhdl_core::diagnostic::report::show_source_detail;
 use rhdl_core::{
-    compile_design, generate_verilog, note, note_init_db, note_take, note_time,
+    compile_design, generate_verilog, note, note_init_db, note_take_vcd, note_time,
     test_module::TestModule, Digital, DigitalFn,
 };
 use rhdl_core::{KernelFnKind, Synchronous, UpdateFn};
@@ -283,7 +283,7 @@ fn test_strobe_simulation() {
     let outputs = simulate(strobe, enable).filter(|x| *x).count();
     eprintln!("outputs: {}, elapsed {:?}", outputs, now.elapsed());
     let mut vcd_file = std::fs::File::create("strobe.vcd").unwrap();
-    note_take().dump_vcd(&[], &mut vcd_file).unwrap();
+    note_take_vcd(&[], &mut vcd_file).unwrap();
 }
 
 #[test]
@@ -294,7 +294,7 @@ fn test_start_pulse_simulation() {
     let outputs = simulate(pulse, input).filter(|x| *x).count();
     assert_eq!(outputs, 1);
     let mut vcd_file = std::fs::File::create("start_pulse.vcd").unwrap();
-    note_take().dump_vcd(&[], &mut vcd_file).unwrap();
+    note_take_vcd(&[], &mut vcd_file).unwrap();
 }
 
 #[test]
@@ -307,7 +307,7 @@ fn test_one_shot_simulation() {
     note_init_db();
     let outputs = simulate(one_shot, input).filter(|x| *x).count();
     let mut vcd_file = std::fs::File::create("one_shot.vcd").unwrap();
-    note_take().dump_vcd(&[], &mut vcd_file).unwrap();
+    note_take_vcd(&[], &mut vcd_file).unwrap();
 }
 
 #[test]
@@ -320,7 +320,7 @@ fn test_pulser_simulation() {
     note_init_db();
     let outputs = simulate(pulser, input).filter(|x| *x).count();
     let mut vcd_file = std::fs::File::create("pulser.vcd").unwrap();
-    note_take().dump_vcd(&[], &mut vcd_file).unwrap();
+    note_take_vcd(&[], &mut vcd_file).unwrap();
 }
 
 #[test]
diff --git a/rhdl/src/tests.rs b/rhdl/src/tests.rs
index 615c7c34..c4d31d58 100644
--- a/rhdl/src/tests.rs
+++ b/rhdl/src/tests.rs
@@ -7,7 +7,7 @@ use rhdl_core::{
     kernel::{self, Kernel},
     note,
     note_db::note_time,
-    note_init_db, note_take,
+    note_init_db, note_take_vcd,
     path::{bit_range, Path},
     rhif::vm::execute_function,
     test_kernel_vm_and_verilog, Digital, KernelFnKind, Kind,
@@ -46,7 +46,7 @@ fn test_vcd_enum() {
     note_time(8_000);
     note("enum", Enum::None);
     let mut vcd_file = std::fs::File::create("test_enum.vcd").unwrap();
-    note_take().dump_vcd(&[], &mut vcd_file).unwrap();
+    note_take_vcd(&[], &mut vcd_file).unwrap();
 }
 
 #[test]
@@ -73,7 +73,7 @@ fn test_vcd_basic() {
     note_time(2_000);
     note("simple", simple);
     let mut vcd_file = std::fs::File::create("test.vcd").unwrap();
-    note_take().dump_vcd(&[], &mut vcd_file).unwrap();
+    note_take_vcd(&[], &mut vcd_file).unwrap();
 }
 
 #[test]
@@ -199,7 +199,7 @@ fn test_derive_digital_complex_enum() {
     note_time(3_000);
     note("test", foo_1);
     let mut vcd_file = std::fs::File::create("test_enum.vcd").unwrap();
-    note_take().dump_vcd(&[], &mut vcd_file).unwrap();
+    note_take_vcd(&[], &mut vcd_file).unwrap();
 }
 
 #[test]
diff --git a/rhdl/tests/complex_enum.rs b/rhdl/tests/complex_enum.rs
index 7650b393..bc48c924 100644
--- a/rhdl/tests/complex_enum.rs
+++ b/rhdl/tests/complex_enum.rs
@@ -1,6 +1,6 @@
 use rhdl_bits::alias::*;
 use rhdl_core::{
-    note, note_init_db, note_take, note_time,
+    note, note_init_db, note_take_vcd, note_time,
     path::{Path, PathElement},
     Digital, Kind,
 };
@@ -241,5 +241,5 @@ fn test_vcd_generation() {
     note_time(6_000);
     note("packet", Packet::State(State::Running));
     let mut vcd_file = std::fs::File::create("packet.vcd").unwrap();
-    note_take().dump_vcd(&[], vcd_file).unwrap();
+    note_take_vcd(&[], vcd_file).unwrap();
 }

From 2974f2b658c3b67a9b3802e33ad65e216e7b7914 Mon Sep 17 00:00:00 2001
From: Zebreus <lennart@zebre.us>
Date: Sat, 25 May 2024 19:35:29 +0200
Subject: [PATCH 4/4] Rename note_init_db to note_reset_db

---
 rhdl-core/src/lib.rs       |  2 +-
 rhdl-core/src/note_db.rs   | 24 ++++++++++++------------
 rhdl-x/src/main.rs         | 10 +++++-----
 rhdl-x/src/push_pull.rs    |  6 +++---
 rhdl/src/synchronous.rs    | 10 +++++-----
 rhdl/src/tests.rs          |  8 ++++----
 rhdl/tests/complex_enum.rs |  4 ++--
 7 files changed, 32 insertions(+), 32 deletions(-)

diff --git a/rhdl-core/src/lib.rs b/rhdl-core/src/lib.rs
index c50eb64e..effbc6d9 100644
--- a/rhdl-core/src/lib.rs
+++ b/rhdl-core/src/lib.rs
@@ -44,7 +44,7 @@ pub use codegen::verilog::generate_verilog;
 pub use codegen::verilog::VerilogModule;
 pub use compiler::compile_design;
 pub use note_db::note;
-pub use note_db::note_init_db;
+pub use note_db::note_reset_db;
 pub use note_db::note_pop_path;
 pub use note_db::note_push_path;
 pub use note_db::note_take_vcd;
diff --git a/rhdl-core/src/note_db.rs b/rhdl-core/src/note_db.rs
index 1218f8ca..0dfbbdbe 100644
--- a/rhdl-core/src/note_db.rs
+++ b/rhdl-core/src/note_db.rs
@@ -10,7 +10,7 @@
 //!
 //! ```
 //! use rhdl::{bits::bits, synchronous::{simulate, OneShot}};
-//! use rhdl_core::{note_init_db, note_take_vcd};
+//! use rhdl_core::{note_reset_db, note_take_vcd};
 //!
 //! // Simulate device
 //! let inputs = vec![false, true, false, false, false, false, false, false].into_iter();
@@ -25,9 +25,9 @@
 //! Use the notetaking functions outside of a simulation:
 //!
 //! ```
-//! use rhdl_core::{note, note_init_db, note_time, note_take_vcd};
+//! use rhdl_core::{note, note_reset_db, note_time, note_take_vcd};
 //! // Reset db
-//! note_init_db();
+//! note_reset_db();
 //!
 //! // Note some values
 //! note("a", false);
@@ -620,21 +620,21 @@ thread_local! {
 /// Reset the note database singleton:
 ///
 /// ```
-/// use rhdl_core::{note_init_db, note};
+/// use rhdl_core::{note_reset_db, note};
 ///
 /// // Note some values
 /// note("a", false);
 /// note("b", 6);
 ///
 /// // Reset the note database
-/// note_init_db();
+/// note_reset_db();
 ///
 /// // The note database is now empty again
 /// ```
 ///
 /// See [`note_db`](crate::note_db#examples) for more examples.
-pub fn note_init_db() {
-    DB.replace(NoteDB::default());
+pub fn note_reset_db() {
+    DB.take();
 }
 
 /// Add a path to path stack in the design hierarchy.
@@ -707,7 +707,7 @@ pub fn note(key: impl NoteKey, value: impl Notable) {
 
 /// Take and dump the note database singleton to a VCD file.
 ///
-/// This will dump the note database to a VCD file and replace it with a new empty note database. The VCD dump will contain all the values that have been noted since the last [`note_take_vcd`] or [`note_init_db`].
+/// This will dump the note database to a VCD file and replace it with a new empty note database. The VCD dump will contain all the values that have been noted since the last [`note_take_vcd`] or [`note_reset_db`].
 ///
 /// The `clocks` parameter can be used to add additional [`ClockDetails`] for reference.
 /// # Examples
@@ -733,7 +733,7 @@ pub fn note(key: impl NoteKey, value: impl Notable) {
 /// After calling `note_take_vcd`, the note database will be empty:
 ///
 /// ```
-/// use rhdl_core::{note, note_init_db, note_time, note_take_vcd};
+/// use rhdl_core::{note, note_reset_db, note_time, note_take_vcd};
 ///
 /// // Note some values
 /// note("a", false);
@@ -766,7 +766,7 @@ mod tests {
 
     #[test]
     fn test_vcd_write() {
-        note_init_db();
+        note_reset_db();
         for i in 0..1000 {
             note_time(i * 1000);
             note("a", i % 2 == 0);
@@ -904,7 +904,7 @@ mod tests {
             }
         }
 
-        note_init_db();
+        note_reset_db();
         note_time(0);
         note("a", Mixed::None);
         note_time(100);
@@ -931,7 +931,7 @@ mod tests {
 
     #[test]
     fn test_vcd_with_nested_paths() {
-        note_init_db();
+        note_reset_db();
         for i in 0..10 {
             note_time(i * 1000);
             note_push_path("fn1");
diff --git a/rhdl-x/src/main.rs b/rhdl-x/src/main.rs
index e26b1f7e..116d3a5b 100644
--- a/rhdl-x/src/main.rs
+++ b/rhdl-x/src/main.rs
@@ -9,9 +9,9 @@ use petgraph::dot::Dot;
 use rhdl_bits::alias::*;
 use rhdl_core::compile_design;
 use rhdl_core::note_db::note_time;
-use rhdl_core::note_init_db;
 use rhdl_core::note_pop_path;
 use rhdl_core::note_push_path;
+use rhdl_core::note_reset_db;
 use rhdl_core::note_take_vcd;
 use rhdl_core::Circuit;
 use rhdl_core::DigitalFn;
@@ -86,7 +86,7 @@ fn test_dff() {
     let clock = clock::clock();
     let data = (0..10).cycle();
     let inputs = clock.zip(data).map(|(clock, data)| DFFI { clock, data });
-    note_init_db();
+    note_reset_db();
     note_time(0);
     let dff = DFF::<u8>::default();
     let mut state = dff.init_state();
@@ -108,7 +108,7 @@ fn test_strobe() {
     let inputs = clock
         .zip(enable)
         .map(|(clock, enable)| StrobeI { clock, enable });
-    note_init_db();
+    note_reset_db();
     note_time(0);
     let strobe = Strobe::<8>::new(b8(5));
     let mut state = strobe.init_state();
@@ -166,7 +166,7 @@ fn main() {
     let inputs = clock
         .zip(enable)
         .map(|(clock, enable)| CounterI { clock, enable });
-    note_init_db();
+    note_reset_db();
     note_time(0);
     let counter = Counter::<8>::default();
     let mut state = counter.init_state();
@@ -190,7 +190,7 @@ fn test_timing_note() {
         B,
         C,
     };
-    note_init_db();
+    note_reset_db();
     note_time(0);
     let tic = Instant::now();
     for i in 0..1_000_000 {
diff --git a/rhdl-x/src/push_pull.rs b/rhdl-x/src/push_pull.rs
index 5e79fc1d..fc481fe2 100644
--- a/rhdl-x/src/push_pull.rs
+++ b/rhdl-x/src/push_pull.rs
@@ -3,9 +3,9 @@ use rhdl_bits::alias::*;
 use rhdl_bits::Bits;
 use rhdl_core::circuit::circuit_impl::CircuitUpdateFn;
 use rhdl_core::note;
-use rhdl_core::note_init_db;
 use rhdl_core::note_pop_path;
 use rhdl_core::note_push_path;
+use rhdl_core::note_reset_db;
 use rhdl_core::note_take_vcd;
 use rhdl_core::note_time;
 use rhdl_core::root_descriptor;
@@ -423,7 +423,7 @@ fn test_simulate_push() {
     };
     let mut state = push.init_state();
     let mut io = <Push as Circuit>::Z::default();
-    note_init_db();
+    note_reset_db();
     note_time(0);
     note_push_path("top");
     for (ndx, input) in crate::clock::clock().take(1500).enumerate() {
@@ -599,7 +599,7 @@ fn test_simulate_push_pair() {
     };
     let mut state = push_pair.init_state();
     eprintln!("State: {:?}", state);
-    note_init_db();
+    note_reset_db();
     note_time(0);
     let mut io = <PushPair as Circuit>::Z::default();
     for (ndx, input) in crate::clock::clock().take(1500).enumerate() {
diff --git a/rhdl/src/synchronous.rs b/rhdl/src/synchronous.rs
index 7914cc16..ed27954c 100644
--- a/rhdl/src/synchronous.rs
+++ b/rhdl/src/synchronous.rs
@@ -16,7 +16,7 @@ use rhdl_bits::{bits, Bits};
 use rhdl_core::ast::ast_impl::KernelFn;
 //use rhdl_core::diagnostic::report::show_source_detail;
 use rhdl_core::{
-    compile_design, generate_verilog, note, note_init_db, note_take_vcd, note_time,
+    compile_design, generate_verilog, note, note_reset_db, note_take_vcd, note_time,
     test_module::TestModule, Digital, DigitalFn,
 };
 use rhdl_core::{KernelFnKind, Synchronous, UpdateFn};
@@ -279,7 +279,7 @@ fn test_strobe_simulation() {
     let enable = std::iter::repeat(true).take(1_000_000);
     let strobe = Strobe::<16> { period: bits(100) };
     let now = std::time::Instant::now();
-    note_init_db();
+    note_reset_db();
     let outputs = simulate(strobe, enable).filter(|x| *x).count();
     eprintln!("outputs: {}, elapsed {:?}", outputs, now.elapsed());
     let mut vcd_file = std::fs::File::create("strobe.vcd").unwrap();
@@ -290,7 +290,7 @@ fn test_strobe_simulation() {
 fn test_start_pulse_simulation() {
     let input = std::iter::repeat(()).take(100);
     let pulse = StartPulse {};
-    note_init_db();
+    note_reset_db();
     let outputs = simulate(pulse, input).filter(|x| *x).count();
     assert_eq!(outputs, 1);
     let mut vcd_file = std::fs::File::create("start_pulse.vcd").unwrap();
@@ -304,7 +304,7 @@ fn test_one_shot_simulation() {
         .cycle()
         .take(1000);
     let one_shot = OneShot::<16> { duration: bits(10) };
-    note_init_db();
+    note_reset_db();
     let outputs = simulate(one_shot, input).filter(|x| *x).count();
     let mut vcd_file = std::fs::File::create("one_shot.vcd").unwrap();
     note_take_vcd(&[], &mut vcd_file).unwrap();
@@ -317,7 +317,7 @@ fn test_pulser_simulation() {
         one_shot: OneShot::<16> { duration: bits(20) },
         strobe: Strobe::<16> { period: bits(100) },
     };
-    note_init_db();
+    note_reset_db();
     let outputs = simulate(pulser, input).filter(|x| *x).count();
     let mut vcd_file = std::fs::File::create("pulser.vcd").unwrap();
     note_take_vcd(&[], &mut vcd_file).unwrap();
diff --git a/rhdl/src/tests.rs b/rhdl/src/tests.rs
index c4d31d58..d54c204a 100644
--- a/rhdl/src/tests.rs
+++ b/rhdl/src/tests.rs
@@ -7,7 +7,7 @@ use rhdl_core::{
     kernel::{self, Kernel},
     note,
     note_db::note_time,
-    note_init_db, note_take_vcd,
+    note_reset_db, note_take_vcd,
     path::{bit_range, Path},
     rhif::vm::execute_function,
     test_kernel_vm_and_verilog, Digital, KernelFnKind, Kind,
@@ -25,7 +25,7 @@ fn test_vcd_enum() {
         C(bool),
     }
 
-    note_init_db();
+    note_reset_db();
     note_time(0);
     note("enum", Enum::None);
     note("color", bits::<8>(0b10101010));
@@ -61,7 +61,7 @@ fn test_vcd_basic() {
         a: true,
         b: Bits::from(0b10101010),
     };
-    note_init_db();
+    note_reset_db();
     note_time(0);
     note("simple", simple);
     note_time(1_000);
@@ -189,7 +189,7 @@ fn test_derive_digital_complex_enum() {
     println!("foo val: {}", foo_2.binary_string());
 
     let foo_3 = Test::A;
-    note_init_db();
+    note_reset_db();
     note_time(0);
     note("test", foo_1);
     note_time(1_000);
diff --git a/rhdl/tests/complex_enum.rs b/rhdl/tests/complex_enum.rs
index bc48c924..eb8e1695 100644
--- a/rhdl/tests/complex_enum.rs
+++ b/rhdl/tests/complex_enum.rs
@@ -1,6 +1,6 @@
 use rhdl_bits::alias::*;
 use rhdl_core::{
-    note, note_init_db, note_take_vcd, note_time,
+    note, note_reset_db, note_take_vcd, note_time,
     path::{Path, PathElement},
     Digital, Kind,
 };
@@ -203,7 +203,7 @@ fn test_documentation_svgs() {
 
 #[test]
 fn test_vcd_generation() {
-    note_init_db();
+    note_reset_db();
     note_time(0);
     note(
         "packet",