From 3c88e05331af142826ac4cafe56c7536f4d0ae2f Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Sun, 13 Sep 2026 08:29:19 -0700
Subject: Better comments

Also removed unneccesary section from readme
---
 src/online_crossbar.c | 18 +++++++++++++++++-
 src/read_crossbar.c   |  3 ++-
 2 files changed, 19 insertions(+), 2 deletions(-)

(limited to 'src')

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>
-- 
cgit v1.2.3