f729045cbe16179aad8afdddde80c457a335608e

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>

diff --git a/include/avr_mcu_section.h b/include/avr_mcu_section.h
index 8991ac5ce55d852601c6d18bc9794de784fa82f9..fca11c63c9c06e0f543757ce3c8d23389dffc91a 100644 (file)
--- 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