Better commentsmain

Also removed unneccesary section from readme

10 files changed, 19 insertions, 20 deletions

diff --git a/README.md b/README.md
index b5787fd..35959cc 100644
--- a/README.md
+++ b/README.md
@@ -74,21 +74,3 @@ make run MODE=offline
 
 The benchmark prints the mean squared error for each device model and writes
 generated netlists, simulation data, and SVG plots under `output/`.
-
-## Embedded deployment
-
-The shared-ngspice backend targets a general-purpose computer. Typical
-microcontrollers do not have the memory, numerical libraries, filesystem, or
-operating-system services required to run ngspice.
-
-For an embedded deployment, a small SPIRES reservoir (for example, up to 16
-neurons) can run on a microcontroller and transmit each state vector to a host
-computer. The host runs the persistent ngspice crossbar and returns the decoded
-prediction. A fixed-size binary protocol should include a timestep number, the
-state values, and integrity checking so missing or reordered messages can be
-detected.
-
-The producer/consumer pipeline remains useful in that configuration, but the
-concurrency spans the microcontroller and host. The two-thread local
-implementation is primarily useful when both the software reservoir and ngspice
-readout run on the same general-purpose computer.
diff --git a/bin/benchmark b/bin/benchmark
index 36680a6..b1e85d9 100755
--- a/bin/benchmark
+++ b/bin/benchmark
diff --git a/build/application.o b/build/application.o
index 66e9c44..2c4e2ef 100644
--- a/build/application.o
+++ b/build/application.o
diff --git a/build/benchmark.o b/build/benchmark.o
index 906f19b..08a8003 100644
--- a/build/benchmark.o
+++ b/build/benchmark.o
diff --git a/build/crossbar_generator.o b/build/crossbar_generator.o
index 23dcbf9..873cb9e 100644
--- a/build/crossbar_generator.o
+++ b/build/crossbar_generator.o
diff --git a/build/online_crossbar.o b/build/online_crossbar.o
index dae53a4..bc23622 100644
--- a/build/online_crossbar.o
+++ b/build/online_crossbar.o
diff --git a/build/read_crossbar.o b/build/read_crossbar.o
index 6c86243..101e4f5 100644
--- a/build/read_crossbar.o
+++ b/build/read_crossbar.o
diff --git a/build/spires_interface.o b/build/spires_interface.o
index 986d773..5264e61 100644
--- a/build/spires_interface.o
+++ b/build/spires_interface.o
diff --git a/src/online_crossbar.c b/src/online_crossbar.c
index ff346bd..b18dd97 100644
--- a/src/online_crossbar.c
+++ b/src/online_crossbar.c
@@ -3,11 +3,12 @@
 #include "crossbar_generator.h"
 #include "read_crossbar.h"
 
+#include <stdbool.h>
+
 #include <ctype.h>
 #include <math.h>
 #include <ngspice/sharedspice.h>
 #include <pthread.h>
-#include <stdbool.h>
 #include <stdint.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -33,6 +34,7 @@ struct Online_Crossbar {
 	pthread_cond_t progress;
 };
 
+// checks that the online crossbar configuration is valid
 static int config_is_valid(const Online_Crossbar_Config *config)
 {
 	if (!config || config->num_neurons == 0 || config->num_outputs == 0 ||
@@ -59,6 +61,7 @@ static int config_is_valid(const Online_Crossbar_Config *config)
 	return isfinite(stop_time) && stop_time > 0.0;
 }
 
+// ignores random ngspice output, unless its an error
 static int callback_text(char *text, int ident, void *user_data)
 {
 	(void)ident;
@@ -71,6 +74,7 @@ static int callback_text(char *text, int ident, void *user_data)
 	return 0;
 }
 
+// ignores ngspice vector information that the benchmark does not need
 static int callback_init_data(pvecinfoall values, int ident, void *user_data)
 {
 	(void)values;
@@ -79,6 +83,7 @@ static int callback_init_data(pvecinfoall values, int ident, void *user_data)
 	return 0;
 }
 
+// marks the simulation as failed and wakes any waiting threads
 static void fail_locked(Online_Crossbar *crossbar)
 {
 	crossbar->failed = 1;
@@ -86,6 +91,7 @@ static void fail_locked(Online_Crossbar *crossbar)
 	pthread_cond_broadcast(&crossbar->progress);
 }
 
+// marks the simulation as failed if ngspice exits unexpectedly
 static int callback_exit(int status, NG_BOOL immediate, NG_BOOL quit_exit,
 			 int ident, void *user_data)
 {
@@ -100,6 +106,7 @@ static int callback_exit(int status, NG_BOOL immediate, NG_BOOL quit_exit,
 	return 0;
 }
 
+// records when the ngspice background simulation finishes
 static int callback_background(NG_BOOL running, int ident, void *user_data)
 {
 	(void)ident;
@@ -119,6 +126,7 @@ static int callback_background(NG_BOOL running, int ident, void *user_data)
 	return 0;
 }
 
+// gets the crossbar row number from an ngspice source name
 static int row_from_name(const char *name, size_t *row_out)
 {
 	const char *digits = name + strlen(name);
@@ -137,6 +145,7 @@ static int row_from_name(const char *name, size_t *row_out)
 	return 0;
 }
 
+// converts the current ngspice simulation time into a reservoir timestep
 static size_t timestep_for_time(const Online_Crossbar *crossbar, double time)
 {
 	if (time <= 0.0) {
@@ -152,6 +161,7 @@ static size_t timestep_for_time(const Online_Crossbar *crossbar, double time)
 	return timestep;
 }
 
+// gives ngspice the reservoir voltage for a requested crossbar row
 static int callback_voltage(double *voltage, double time, char *name, int ident,
 			    void *user_data)
 {
@@ -187,6 +197,7 @@ static int callback_voltage(double *voltage, double time, char *name, int ident,
 	return 0;
 }
 
+// collects and decodes crossbar output voltages at each timestep
 static int callback_data(pvecvaluesall values, int count, int ident,
 			 void *user_data)
 {
@@ -274,6 +285,7 @@ static int callback_data(pvecvaluesall values, int count, int ident,
 	return 0;
 }
 
+// allocates the online crossbar and generates its ngspice netlist
 int online_crossbar_init(const Online_Crossbar_Config *config,
 			 const spires_reservoir *reservoir,
 			 Online_Crossbar **crossbar_out)
@@ -341,6 +353,7 @@ fail:
 	return -1;
 }
 
+// starts the persistent ngspice simulation in the background
 int online_crossbar_start(Online_Crossbar *crossbar)
 {
 	if (!crossbar || crossbar->started) {
@@ -375,6 +388,7 @@ int online_crossbar_start(Online_Crossbar *crossbar)
 	return 0;
 }
 
+// submits one reservoir state and returns the previous timestep's output
 int online_crossbar_submit(Online_Crossbar *crossbar, size_t timestep,
 			   const double *state, double *previous_output,
 			   int *output_ready)
@@ -419,6 +433,7 @@ int online_crossbar_submit(Online_Crossbar *crossbar, size_t timestep,
 	return 0;
 }
 
+// waits for and returns the final crossbar output
 int online_crossbar_finish(Online_Crossbar *crossbar, double *final_output)
 {
 	if (!crossbar || !final_output ||
@@ -442,6 +457,7 @@ int online_crossbar_finish(Online_Crossbar *crossbar, double *final_output)
 	return 0;
 }
 
+// stops ngspice and frees all online crossbar resources
 void online_crossbar_destroy(Online_Crossbar *crossbar)
 {
 	if (!crossbar) {
diff --git a/src/read_crossbar.c b/src/read_crossbar.c
index 0825147..ed17a9e 100644
--- a/src/read_crossbar.c
+++ b/src/read_crossbar.c
@@ -1,8 +1,9 @@
 #include "read_crossbar.h"
 
-#include <ngspice/sharedspice.h>
 #include <stdbool.h>
 
+#include <ngspice/sharedspice.h>
+
 #include <sched.h>
 #include <stdint.h>
 #include <stdio.h>