From ab4e337a188c4b74c26733fdb2d1183e3badb47c Mon Sep 17 00:00:00 2001
From: Mark Qvist <markq@qvistconsult.com>
Date: Sun, 6 Apr 2014 19:46:24 +0200
Subject: [PATCH] More commenting

---
 Modem/hardware.c | 26 ++++++++++++++++++++------
 Modem/hardware.h | 37 ++++++++++++++++++++++++++++++++-----
 buildrev.h       |  2 +-
 3 files changed, 53 insertions(+), 12 deletions(-)

diff --git a/Modem/hardware.c b/Modem/hardware.c
index e64b17f..f52b2ed 100644
--- a/Modem/hardware.c
+++ b/Modem/hardware.c
@@ -1,18 +1,32 @@
+//////////////////////////////////////////////////////
+// First things first, all the includes we need     //
+//////////////////////////////////////////////////////
 
-#include "hardware.h"
-#include "afsk.h"
+#include "hardware.h"		// We need the header for this code
+#include "afsk.h"			// We also need to know about the AFSK modem
 
-#include <cpu/irq.h>
-
-#include <avr/io.h>
-#include <avr/interrupt.h>
+#include <cpu/irq.h>		// Interrupt functions from BertOS
 
+#include <avr/io.h>			// AVR IO functions from BertOS
+#include <avr/interrupt.h>	// AVR interrupt functions from BertOS
 
+// A reference to our modem "object"
 static Afsk *context;
 
+//////////////////////////////////////////////////////
+// And now for the actual hardware functions        //
+//////////////////////////////////////////////////////
+
+// This function initializes the ADC and configures
+// it the way we need.
 void hw_afsk_adcInit(int ch, Afsk *_context)
 {
+	// Store a reference to our modem "object"
+	// FIXME: rename this
 	context = _context;
+
+	// Also make sure that we are not trying to use
+	// a pin that can't be used for analog input
 	ASSERT(ch <= 5);
 
 	// We need to do some configuration on the Timer/Counter Control
diff --git a/Modem/hardware.h b/Modem/hardware.h
index 7ecb03a..cdfd4c7 100644
--- a/Modem/hardware.h
+++ b/Modem/hardware.h
@@ -1,19 +1,35 @@
+//////////////////////////////////////////////////////
+// First things first, all the includes we need     //
+//////////////////////////////////////////////////////
 
 #ifndef FSK_MODEM_HW
 #define FSK_MODEM_HW
 
-#include "cfg/cfg_arch.h"
+#include "cfg/cfg_arch.h"	// Architecture configuration
 
-#include <avr/io.h>
+#include <avr/io.h>			// AVR IO functions from BertOS
 
+//////////////////////////////////////////////////////
+// Definitions and some useful macros               //
+//////////////////////////////////////////////////////
+
+// Forward declaration of our modem "object"
 struct Afsk;
+
+// Function declarations
 void hw_afsk_adcInit(int ch, struct Afsk *_ctx);
 void hw_afsk_dacInit(int ch, struct Afsk *_ctx);
 
-// ADC initialization
+// A shorthand macro for initializing the ADC.
+// It just calls the actual ADC initialization code
+// in "hardware.c"
 #define AFSK_ADC_INIT(ch, ctx) hw_afsk_adcInit(ch, ctx)
 
 // Here's some macros for controlling the RX/TX LEDs
+// THE _INIT() functions writes to the DDRB register
+// to configure the pins as output pins, and the _ON()
+// and _OFF() functions writes to the PORT registers
+// to turn the pins on or off.
 #define LED_TX_INIT() do { DDRB |= BV(1); } while (0)
 #define LED_TX_ON()   do { PORTB |= BV(1); } while (0)
 #define LED_TX_OFF()  do { PORTB &= ~BV(1); } while (0)
@@ -28,8 +44,19 @@ void hw_afsk_dacInit(int ch, struct Afsk *_ctx);
 #define PTT_ON()   do { PORTD |= BV(3); } while (0)
 #define PTT_OFF()  do { PORTD &= ~BV(3); } while (0)
 
-// Initialization, start and stop for DAC
-#define AFSK_DAC_INIT(ch, ctx)   do { (void)ch, (void)ctx; DDRD |= 0xF4; DDRB |= BV(3); } while (0)
+// Initialization of the DAC pins. The DDRD register
+// configures pins 0 through 7 for input or output.
+// DDR stands for Data Direction Register. By setting
+// it to 0xF8 we set 11111000, which means the pins
+// 3, 4, 5, 6 and 7 will be set to output.
+// FIXME: remove ch and ctx
+#define AFSK_DAC_INIT(ch, ctx)   do { (void)ch, (void)ctx; DDRD |= 0xF8; DDRB |= BV(3); } while (0)
+
+// These two macros start and stop the DAC being
+// triggered in our timer interrupt. For starting
+// it, we set a boolean flag to true, and false for
+// stopping it. We also turn on and off pin 3 to trigger
+// the PTT of the radio.
 #define AFSK_DAC_IRQ_START(ch)   do { (void)ch; extern bool hw_afsk_dac_isr; PORTB |= BV(3); hw_afsk_dac_isr = true; } while (0)
 #define AFSK_DAC_IRQ_STOP(ch)    do { (void)ch; extern bool hw_afsk_dac_isr; PORTB &= ~BV(3); hw_afsk_dac_isr = false; } while (0)
 
diff --git a/buildrev.h b/buildrev.h
index e2786f7..9d71535 100644
--- a/buildrev.h
+++ b/buildrev.h
@@ -1,2 +1,2 @@
-#define VERS_BUILD 359
+#define VERS_BUILD 361
 #define VERS_HOST  "vixen"