From f729045cbe16179aad8afdddde80c457a335608e Mon Sep 17 00:00:00 2001
From: Michel Pollet <buserror@gmail.com>
Date: Tue, 12 Oct 2010 10:00:33 +0100
Subject: [PATCH] mcu_section: Added New CONSOLE Tag

CONSOLE tag allow declaring a register for dumping debug output
oh the terminal without using an UART

Also cleaned up and documented the header file further

Signed-off-by: Michel Pollet <buserror@gmail.com>
---
 include/avr_mcu_section.h | 91 ++++++++++++++++++++++++++++-----------
 1 file changed, 65 insertions(+), 26 deletions(-)

diff --git a/include/avr_mcu_section.h b/include/avr_mcu_section.h
index 8991ac5..fca11c6 100644
--- a/include/avr_mcu_section.h
+++ b/include/avr_mcu_section.h
@@ -56,6 +56,7 @@ enum {
 	AVR_MMCU_TAG_EFUSE,
 	AVR_MMCU_TAG_SIGNATURE,
 	AVR_MMCU_TAG_SIMAVR_COMMAND,
+	AVR_MMCU_TAG_SIMAVR_CONSOLE,
 	AVR_MMCU_TAG_VCD_FILENAME,
 	AVR_MMCU_TAG_VCD_PERIOD,	
 	AVR_MMCU_TAG_VCD_TRACE,
@@ -98,47 +99,90 @@ struct avr_mmcu_vcd_trace_t {
 } __attribute__((__packed__));
 
 #define AVR_MCU_STRING(_tag, _str) \
-const struct avr_mmcu_string_t _##_tag _MMCU_ = {\
-	.tag = _tag,\
-	.len = sizeof(_str),\
-	.string = _str,\
-}
+	const struct avr_mmcu_string_t _##_tag _MMCU_ = {\
+		.tag = _tag,\
+		.len = sizeof(_str),\
+		.string = _str,\
+	}
 
 #define AVR_MCU_LONG(_tag, _val) \
-const struct avr_mmcu_long_t _##_tag _MMCU_ = {\
-	.tag = _tag,\
-	.len = sizeof(uint32_t),\
-	.val = _val,\
-}
+	const struct avr_mmcu_long_t _##_tag _MMCU_ = {\
+		.tag = _tag,\
+		.len = sizeof(uint32_t),\
+		.val = _val,\
+	}
 
 #define AVR_MCU_BYTE(_tag, _val) \
-const uint8_t _##_tag _MMCU_ = { _tag, 1, _val }
-
+	const uint8_t _##_tag _MMCU_ = { _tag, 1, _val }
+
+/*!
+ * This Macro allows you to specify traces for the VCD file output
+ * engine. This specifies a default header, and let you fill in the
+ * relevant bits.
+ * Example:
+ *	const struct avr_mmcu_vcd_trace_t _mytrace[]  _MMCU_ = {
+ *		{ AVR_MCU_VCD_SYMBOL("UDR0"), .what = (void*)&UDR0, },
+ *		{ AVR_MCU_VCD_SYMBOL("UDRE0"), .mask = (1 << UDRE0), .what = (void*)&UCSR0A, },
+ *	};
+ * This structure will automatically tell simavr to add a VCD trace
+ * for the UART register, and the UDRE0 bit, so you can trace exactly
+ * the timing of the changed using gtkwave.
+ */
 #define AVR_MCU_VCD_SYMBOL(_name) \
 	.tag = AVR_MMCU_TAG_VCD_TRACE, \
 	.len = sizeof(struct avr_mmcu_vcd_trace_t) - 2 + sizeof(_name),\
 	.name = _name
 
-// specified the name and wanted period (usec) for a VCD file
-// thid is not mandatory, a default one will be created if
-// symbols are declared themselves
+/*!
+ * Specifies the name and wanted period (in usec) for a VCD file
+ * this is not mandatory for the VCD output to work, if this tag
+ * is not used, a VCD file will still be created with default values
+ */
 #define AVR_MCU_VCD_FILE(_name, _period) \
 	AVR_MCU_STRING(AVR_MMCU_TAG_VCD_FILENAME, _name);\
 	AVR_MCU_LONG(AVR_MMCU_TAG_VCD_PERIOD, _period)
 
-// It is possible to send "commands" to simavr from the
-// firmware itself. For this to work you need to specify
-// an IO register that is to be used for a write-only
-// bridge. A favourite is one of the usual "GPIO register"
-// that most (all ?) AVR have
+/*!
+ * It is possible to send "commands" to simavr from the
+ * firmware itself. For this to work you need to specify
+ * an IO register that is to be used for a write-only
+ * bridge. A favourite is one of the usual "GPIO register"
+ * that most (all ?) AVR have.
+ * See definition of SIMAVR_CMD_* to see what commands can
+ * be used from your firmware.
+ */
 #define AVR_MCU_SIMAVR_COMMAND(_register) \
 	const struct avr_mmcu_addr_t _simavr_command_register _MMCU_ = {\
 		.tag = AVR_MMCU_TAG_SIMAVR_COMMAND,\
 		.len = sizeof(void *),\
 		.what = (void*)_register, \
 	}
+/*!
+ * Similar to AVR_MCU_SIMAVR_COMMAND, The CONSOLE allows the AVR code
+ * to declare a register (typically a GPIO register, but any unused
+ * register can work...) that will allow printing on the host's console
+ * without using a UART to do debug.
+ */
+#define AVR_MCU_SIMAVR_CONSOLE(_register) \
+	const struct avr_mmcu_addr_t _simavr_command_register _MMCU_ = {\
+		.tag = AVR_MMCU_TAG_SIMAVR_CONSOLE,\
+		.len = sizeof(void *),\
+		.what = (void*)_register, \
+	}
 
-/*
+/*!
+ * This tag allows you to specify the voltages used by your board
+ * It is optional in most cases, but you will need it if you use
+ * ADC module's IRQs. Not specifying it in this case might lead
+ * to a divide-by-zero crash.
+ * The units are Volts*1000 (millivolts)
+ */
+#define AVR_MCU_VOLTAGES(_vcc, _avcc, _aref) \
+	AVR_MCU_LONG(AVR_MMCU_TAG_VCC, (_vcc));\
+	AVR_MCU_LONG(AVR_MMCU_TAG_AVCC, (_avcc));\
+	AVR_MCU_LONG(AVR_MMCU_TAG_AREF, (_aref));
+
+/*!
  * This the has to be used if you want to add other tags to the .mmcu section
  * the _mmcu symbol is used as an anchor to make sure it stays linked in.
  */
@@ -147,11 +191,6 @@ const uint8_t _##_tag _MMCU_ = { _tag, 1, _val }
 	AVR_MCU_STRING(AVR_MMCU_TAG_NAME, _name);\
 	AVR_MCU_LONG(AVR_MMCU_TAG_FREQUENCY, _speed)
 
-#define AVR_MCU_VOLTAGES(_vcc, _avcc, _aref) \
-	AVR_MCU_LONG(AVR_MMCU_TAG_VCC, (_vcc));\
-	AVR_MCU_LONG(AVR_MMCU_TAG_AVCC, (_avcc));\
-	AVR_MCU_LONG(AVR_MMCU_TAG_AREF, (_aref));
-
 #endif /* __AVR__ */
 
 #ifdef __cplusplus
-- 
2.39.5