util/spkmodem-recv: extensive commenting

and with this, i'm now pretty much done modifying grub's
crappy code. this experiment started in 2023 has now
pretty much concluded.

the original GNU code was poorly written, hardcoded
everywhere, and not documented or commented at all.

i had to learn what the code is doing through inference
instead, and i'm pretty sure that these explanations
cover everything. i hope?

maybe the frenchman can explain anything i missed. haha.

Signed-off-by: Leah Rowe <leah@libreboot.org>

util/spkmodem_recv/spkmodem-recv.c

@@ -4,8 +4,22 @@
  * Copyright (c) 2023, 2026 Leah Rowe <leah@libreboot.org>
  *
  * This program receives text encoded as pulses on the PC speaker,
- * and decodes them. This is a special type of interface provided
+ * and decodes them via simple FSK (Frequency Shift Keying)
- * by coreboot and GRUB, for computers that lack serial ports.
+ * demodulation and FIR (Finite Impulse Response) frequency
+ * discriminator.
+ *
+ * It waits for specific tones at specific intervals.
+ * It detects tones within the audio stream and reconstructs
+ * characters bit-by-bit as the encoded modem signal is received.
+ * This is performance-efficient on most CPUs, and has relatively
+ * high tolerance for noisy signals (similar to techniques used
+ * for data stored on audio cassette tapes).
+
+ * This is a special interface provided by coreboot and GNU GRUB,
+ * for computers that lack serial ports (useful for debugging).
+ * Note that GRUB and coreboot can both send these signals; this
+ * tool merely decodes them. This tool does not *encode*, only
+ * decode.
  *
  * Usage example (NOTE: little endian!):
  * parec --channels=1 --rate=48000 --format=s16le | ./spkmodem-recv
@@ -14,7 +28,16 @@
  * modified fork that complies with the OpenBSD Kernel Source
  * File Style Guide (KNF) instead of GNU coding standards; it
  * emphasises strict error handling, portability and code
- * quality, as characterised by OpenBSD projects.
+ * quality, as characterised by OpenBSD projects. Several magic
+ * numbers have been tidied up, calculated (not hardcoded) and
+ * thoroughly explained, unlike in the original version.
+ *
+ * The original version was essentially a blob, masquerading as
+ * source code. This forked source code is therefore the result
+ * of extensive reverse engineering (of the GNU source code)!
+ * This cleaned up code and extensive commenting will thoroughly
+ * explain how the decoding works. This was done as an academic
+ * exercise in 2023, continuing in 2026.
  *
  * This fork of spkmodem-recv is provided with Libreboot releases:
  * https://libreboot.org/
@@ -38,11 +61,11 @@
 #include <unistd.h>
 
 /*
- * spkmodem is essentially used FSK (Frequency Shift Keying)
+ * spkmodem is essentially using FSK (Frequency Shift Keying)
- * with two frequencies: tone A (bit 0) and tone B (bit 1),
+ * with two primary tones representing encoded bits,
- * detected via pulse density inside a given window.
+ * separated by a framing tone.
- * Very cheap on CPU cycles and avoids neeing something more
+ * Very cheap on CPU cycles and avoids needing something more
- * complicated like FFT or Goertzel filters, and tolerates
+ * expensive like FFT or Goertzel filters, and tolerates
  * weak/noisy signals.
  */
 
@@ -52,17 +75,31 @@
 #define SAMPLE_RATE 48000
 
 /*
- * A frame is 5ms, so samples
+ * One analysis frame spans 5 ms.
- * per frame is N / 48000 = 0.005 (5ms)
+ *
- * => N = 0.005 * 48000 = 240
+ *   frame_time = SAMPLES_PER_FRAME / SAMPLE_RATE
+ *
+ * With the default sample rate (48 kHz):
+ *
+ *   frame_time = N / 48000
+ *   0.005 s = N / 48000
+ *   N = 0.005 × 48000 = 240 samples
  */
 #define SAMPLES_PER_FRAME 240
 
-/* = 48000 / 240 = 200 Hz resolution */
+/*
+ * Number of analysis frames per second.
+ *
+ * Each increment in the frequency counters corresponds
+ * roughly to this many Hertz of tone frequency.
+ *
+ * With the default values:
+ *   FRAME_RATE = 48000 / 240 = 200 Hz
+ */
 #define FRAME_RATE ((SAMPLE_RATE) / (SAMPLES_PER_FRAME))
 
 /*
- * Two FIR windows are maintained; one for data done,
+ * Two FIR windows are maintained; one for data tone,
  * and one for the separator tone. They are positioned
  * one frame apart in the ring buffer.
  */
@@ -89,7 +126,9 @@
 #define DATA_TONE_THRESHOLD_HZ 5000
 
 /*
- * Convert tone frequencies within the sliding window, into pulse counts
+ * Convert tone frequency ranges into pulse counts within the
+ * sliding analysis window.
+ *
  * pulse_count ≈ tone_frequency / FRAME_RATE
  * where FRAME_RATE = SAMPLE_RATE / SAMPLES_PER_FRAME.
  */
@@ -103,7 +142,7 @@
 
 /*
  * Sample amplitude threshold used to convert the waveform
- * into a pulse stream. Values near zero regarded as noise.
+ * into a pulse stream. Values near zero are regarded as noise.
  */
 #define THRESHOLD 500
 
@@ -207,6 +246,10 @@ handle_audio(struct decoder_state *st)
 {
 	int sample;
 
+	/*
+	 * If the modem signal disappears for several frames,
+	 * discard the partially assembled character.
+	 */
 	if (st->sample_count > (3 * SAMPLES_PER_FRAME))
 		reset_char(st);
 	if (!valid_signal(st)) {
@@ -222,6 +265,11 @@ handle_audio(struct decoder_state *st)
 		decode_pulse(st);
 }
 
+/*
+ * Verify that the observed pulse densities fall within the
+ * expected ranges for spkmodem tones. This prevents random noise
+ * from being misinterpreted as data.
+ */
 static int
 valid_signal(struct decoder_state *st)
 {
@@ -231,6 +279,9 @@ valid_signal(struct decoder_state *st)
 	    st->freq_data < FREQ_DATA_MAX);
 }
 
+/*
+ * Main demodulation step (moving-sum FIR filter).
+ */
 static void
 decode_pulse(struct decoder_state *st)
 {
@@ -244,11 +295,29 @@ decode_pulse(struct decoder_state *st)
 	sep_pos = st->sep_pos;
 
 	/*
-	 * Moving sum of the last N
+	 * Sliding rectangular FIR (Finite Impulse Response) filter.
-	 * pulses; O(1) per sample.
+	 *
+	 * After thresholding, the signal becomes a stream of 0/1 pulses.
+	 * The decoder measures pulse density over two windows:
+	 *
+	 * freq_data: pulses in the "data" window
+	 * freq_separator: pulses in the "separator" window
+	 *
+	 * Instead of calculating each window every time (O(N) per frame), we
+	 * update the window sums incrementally:
+	 *
+	 *   sum_new = sum_old - pulse_leaving + pulse_entering
+	 *
+	 * This keeps the filter O(1) per sample instead of O(N).
+	 * The technique is equivalent to a rectangular FIR filter
+	 * implemented as a sliding moving sum.
+	 *
+	 * The two windows are exactly SAMPLES_PER_FRAME apart in the ring
+	 * buffer, so the pulse leaving the data window is simultaneously
+	 * entering the separator window.
 	 */
 	old_ring = st->pulse[ringpos];
-	old_sep = st->pulse[sep_pos];
+	old_sep  = st->pulse[sep_pos];
 	st->freq_data -= old_ring;
 	st->freq_data += old_sep;
 	st->freq_separator -= old_sep;
@@ -256,8 +325,12 @@ decode_pulse(struct decoder_state *st)
 	sample = read_sample(st);
 
 	/*
-	 * Noise suppression, with a frequency
+	 * Convert the waveform sample into a pulse (0 or 1).
-	 * tolerancy defined by THRESHOLD.
+	 *
+	 * The unsigned comparison creates a small dead zone near zero,
+	 * suppressing small amplitude noise from microphones or
+	 * cheap ADCs. Real PC speaker tones are far outside this
+	 * range, so they still produce clean pulses.
 	 */
 	if ((unsigned)(sample + THRESHOLD)
 	    > (unsigned)(2 * THRESHOLD))
@@ -268,10 +341,14 @@ decode_pulse(struct decoder_state *st)
 	st->pulse[ringpos] = new_pulse;
 	st->freq_separator += new_pulse;
 
+	/*
+	 * Advance both FIR windows through the ring buffer.
+	 * The separator window always stays one frame ahead
+	 * of the data window.
+	 */
 	ringpos++;
 	if (ringpos >= MAX_SAMPLES)
 		ringpos = 0;
-
 	sep_pos++;
 	if (sep_pos >= MAX_SAMPLES)
 		sep_pos = 0;
@@ -317,6 +394,10 @@ read_sample(struct decoder_state *st)
 	return sample;
 }
 
+/*
+ * Each validated frame contributes one bit of modem data.
+ * Bits are accumulated MSB-first into the ASCII byte.
+ */
 static int
 set_ascii_bit(struct decoder_state *st)
 {