online crossbar inputs

1 files changed, 64 insertions, 2 deletions

diff --git a/src/README.md b/src/README.md
index 48a0c5b..b973527 100644
--- a/src/README.md
+++ b/src/README.md
@@ -11,8 +11,9 @@ and generating plots.
         * const char *subcircuit_name
 
 * **run_benchmark() (int)**
-    * Executes the full crossbar simulation pipeline and stores the decoded
-    crossbar predictions in the passed output array.
+    * Executes the offline crossbar pipeline. It generates a batch netlist from
+    a previously collected state matrix, launches the ngspice executable, reads
+    the output file, and stores the decoded predictions in the output array.
     * parameters
         * const spires_reservoir_config *config
         * spires_reservoir *reservoir
@@ -21,6 +22,19 @@ and generating plots.
         * const char *subcircuit_name
         * double *predictions_out
 
+* **run_online_benchmark() (int)**
+    * Steps SPIRES once per input, streams each live reservoir state to a
+    persistent shared-ngspice crossbar, and stores the one-step-delayed decoded
+    predictions in the output array.
+    * parameters
+        * const spires_reservoir_config *config
+        * spires_reservoir *reservoir
+        * const double *input_series
+        * size_t num_timesteps
+        * const char *model_path
+        * const char *subcircuit_name
+        * double *predictions_out
+
 * **calculate_MSE() (double)**
     * calculates the mean squared error of the predictions against the expected
     values
@@ -86,6 +100,54 @@ Handles generation of the SPICE netlist used to simulate the memristive crossbar
         * const char *output_filename
         * const Crossbar_Config *config
 
+* **generate_online_crossbar() (int)**
+    * Generates a persistent transient netlist whose row voltages are supplied
+    through shared-ngspice external voltage-source callbacks.
+    * parameters
+        * const char *output_filename
+        * const Crossbar_Config *config
+
+
+## online_crossbar.h
+
+Provides the stateful online readout engine used by `run_online_benchmark()`.
+The engine owns the shared-ngspice lifecycle, synchronization state, trained
+weight-to-resistance mapping, bounded state buffer, and decoded result storage.
+
+* **Online_Crossbar_Config struct**
+    * Configures the crossbar dimensions, known run length, SPICE timestep,
+    voltage scale, load and device resistance limits, device model, subcircuit,
+    and generated netlist path.
+
+* **online_crossbar_init() (int)**
+    * Copies the trained SPIRES readout weights, maps them into differential
+    resistances, allocates the bounded pipeline, and generates the external-source
+    netlist.
+
+* **online_crossbar_start() (int)**
+    * Initializes shared-ngspice, loads the netlist, installs the first timestep
+    breakpoint, and starts the transient simulation on the ngspice worker thread.
+
+* **online_crossbar_submit() (int)**
+    * Submits `state[t]` with bounded backpressure. Submission `t = 0` reports
+    that no output is ready. Each later submission returns decoded output
+    `t - 1`.
+
+* **online_crossbar_finish() (int)**
+    * Waits for and returns the decoded output associated with the final
+    submitted state.
+
+* **online_crossbar_destroy() (void)**
+    * Stops a running simulation if necessary, waits for its callbacks to exit,
+    resets shared-ngspice, and releases all synchronization and data storage.
+
+The online simulation remains continuous for the full known run length, so
+stateful memristor models retain their internal state between reservoir
+timesteps. Explicit SPICE breakpoints guarantee that a result is emitted before
+the pipeline requests a state that has not yet been published. At most one
+future state is buffered; slow crossbar evaluation therefore blocks the
+producer instead of dropping or reordering data.
+
 
 ## spires_interface.h