[Asterisk-code-review] dsp.c: Added descriptive comments to Goertzel calculations. (asterisk[14])

[Joshua Colp]

Joshua Colp has submitted this change and it was merged.

Change subject: dsp.c: Added descriptive comments to Goertzel calculations.
......................................................................


dsp.c: Added descriptive comments to Goertzel calculations.

* Added doxygen to describe some struct members and what is going on in
the code.

Change-Id: I2ec706a33b52aee42b16dcc356c2bd916a45190d
---
M main/dsp.c
1 file changed, 22 insertions(+), 3 deletions(-)

Approvals:
  George Joseph: Looks good to me, but someone else must approve
  Joshua Colp: Looks good to me, approved; Verified



diff --git a/main/dsp.c b/main/dsp.c
index cbbf696..5c46730 100644
--- a/main/dsp.c
+++ b/main/dsp.c
@@ -238,9 +238,13 @@
 #define CONFIG_FILE_NAME "dsp.conf"
 
 typedef struct {
+	/*! The previous previous sample calculation (No binary point just plain int) */
 	int v2;
+	/*! The previous sample calculation (No binary point just plain int) */
 	int v3;
+	/*! v2 and v3 power of two exponent to keep value in int range */
 	int chunky;
+	/*! 15 bit fixed point goertzel coefficient = 2 * cos(2 * pi * freq / sample_rate) */
 	int fac;
 } goertzel_state_t;
 
@@ -326,12 +330,22 @@
 {
 	int v1;
 
+	/*
+	 * Shift previous values so
+	 * v1 is previous previous value
+	 * v2 is previous value
+	 * until the new v3 is calculated.
+	 */
 	v1 = s->v2;
 	s->v2 = s->v3;
 
+	/* Discard the binary fraction introduced by s->fac */
 	s->v3 = (s->fac * s->v2) >> 15;
+	/* Scale sample to match previous values */
 	s->v3 = s->v3 - v1 + (sample >> s->chunky);
-	if (abs(s->v3) > 32768) {
+
+	if (abs(s->v3) > (1 << 15)) {
+		/* The result is now too large so increase the chunky power. */
 		s->chunky++;
 		s->v3 = s->v3 >> 1;
 		s->v2 = s->v2 >> 1;
@@ -341,21 +355,26 @@
 static inline float goertzel_result(goertzel_state_t *s)
 {
 	goertzel_result_t r;
+
 	r.value = (s->v3 * s->v3) + (s->v2 * s->v2);
 	r.value -= ((s->v2 * s->v3) >> 15) * s->fac;
+	/*
+	 * We have to double the exponent because we multiplied the
+	 * previous sample calculation values together.
+	 */
 	r.power = s->chunky * 2;
 	return (float)r.value * (float)(1 << r.power);
 }
 
 static inline void goertzel_init(goertzel_state_t *s, float freq, unsigned int sample_rate)
 {
-	s->v2 = s->v3 = s->chunky = 0.0;
+	s->v2 = s->v3 = s->chunky = 0;
 	s->fac = (int)(32768.0 * 2.0 * cos(2.0 * M_PI * freq / sample_rate));
 }
 
 static inline void goertzel_reset(goertzel_state_t *s)
 {
-	s->v2 = s->v3 = s->chunky = 0.0;
+	s->v2 = s->v3 = s->chunky = 0;
 }
 
 typedef struct {

-- 
To view, visit https://gerrit.asterisk.org/3344
To unsubscribe, visit https://gerrit.asterisk.org/settings

Gerrit-MessageType: merged
Gerrit-Change-Id: I2ec706a33b52aee42b16dcc356c2bd916a45190d
Gerrit-PatchSet: 2
Gerrit-Project: asterisk
Gerrit-Branch: 14
Gerrit-Owner: Richard Mudgett <rmudgett at digium.com>
Gerrit-Reviewer: Anonymous Coward #1000019
Gerrit-Reviewer: George Joseph <gjoseph at digium.com>
Gerrit-Reviewer: Joshua Colp <jcolp at digium.com>
Gerrit-Reviewer: Mark Michelson <mmichelson at digium.com>