Board-specific values; corresponding QA test generalizations.

Various board-specific #defines and arrays of pins added.

For the changelog (some of this information predates this commit):

* wirish/boards.h now declares the following arrays of pin numbers:

      * boardPWMPins - PWM-capable pins
      * boardADCPins - ADC-capable pins
      * boardUsedPins - pins already in use, e.g. BOARD_BUTTON_PIN

  It also declares a bool boardUsesPin(uint8 pin) function for
  convenient testing of whether a pin is in use.

* wirish/boards/*.h now define:

      * BOARD_USART1_TX_PIN
      * BOARD_USART1_RX_PIN
      * BOARD_USART2_TX_PIN
      * BOARD_USART2_RX_PIN
      * BOARD_USART3_TX_PIN
      * BOARD_USART3_RX_PIN
      * BOARD_NR_GPIO_PINS (renamed from NR_GPIO_PINS)
      * BOARD_NR_USARTS (renamed from NR_USARTS)
      * BOARD_NR_PWM_PINS
      * BOARD_NR_ADC_PINS
      * BOARD_NR_USED_PINS

* wirish/boards/maple_native.h now defines:

      * BOARD_UART4_TX_PIN
      * BOARD_UART4_RX_PIN
      * BOARD_UART5_TX_PIN
      * BOARD_UART5_RX_PIN

  (Unfortunately, wirish/boards/maple_RET6.h cannot, since at least
  one of the UART4/UART5 pins are used already; this will require layout
  changes for a wide-release Maple form factor RET6 board).

* wirish/boards/*.cpp all include the corresponding array definitions.
  They all live in flash by default, thanks to the new __FLASH__ macro
  in wirish/wirish_types.h, which is a synonym for the existing __attr_flash
  #define in libmaple/libmaple_types.h.

The documentation was updated to include this information.  It also
gained various FIXME/TODO comments related to its generalization
across boards.

The quality assurance-related examples (examples/qa-slave-shield.cpp
and examples/test-session.cpp) now make heavy use of board-specific
values to ensure portability.

15 files changed, 158 insertions, 38 deletions

diff --git a/wirish/boards.cpp b/wirish/boards.cpp
index 17f47c6..1c2b1c7 100644
--- a/wirish/boards.cpp
+++ b/wirish/boards.cpp
@@ -30,7 +30,7 @@
  * at 72MHz.  APB1 is clocked at 36MHz.
  */
 
-#include "wirish.h"
+#include "boards.h"
 
 #include "flash.h"
 #include "rcc.h"
@@ -46,15 +46,6 @@ static void setupClocks(void);
 static void setupADC(void);
 static void setupTimers(void);
 
-/**
- * @brief Generic board initialization function.
- *
- * This function is called before main().  It ensures that the clocks
- * and peripherals are configured properly for use with wirish, then
- * calls boardInit().
- *
- * @see boardInit()
- */
 void init(void) {
     setupFlash();
     setupClocks();
@@ -68,6 +59,17 @@ void init(void) {
     boardInit();
 }
 
+/* You could farm this out to the files in boards/ if e.g. it takes
+ * too long to test on Maple Native (all those FSMC pins...). */
+bool boardUsesPin(uint8 pin) {
+    for (int i = 0; i < BOARD_NR_USED_PINS; i++) {
+        if (pin == boardUsedPins[i]) {
+            return true;
+        }
+    }
+    return false;
+}
+
 static void setupFlash(void) {
     flash_enable_prefetch();
     flash_set_latency(FLASH_WAIT_STATE_2);
diff --git a/wirish/boards.h b/wirish/boards.h
index 3d023ae..cec844f 100644
--- a/wirish/boards.h
+++ b/wirish/boards.h
@@ -63,8 +63,39 @@ enum {
  * @brief Maps each Maple pin to a corresponding stm32_pin_info.
  * @see stm32_pin_info
  */
-extern stm32_pin_info PIN_MAP[];
+extern const stm32_pin_info PIN_MAP[];
 
+/**
+ * @brief Pins capable of PWM output.
+ *
+ * Its length is BOARD_NR_PWM_PINS.
+ */
+extern const uint8 boardPWMPins[];
+
+/**
+ * @brief Array of pins capable of analog input.
+ *
+ * Its length is BOARD_NR_ADC_PINS.
+ */
+extern const uint8 boardADCPins[];
+
+/**
+ * @brief Pins which are connected to external hardware.
+ *
+ * For example, on Maple boards, it always at least includes
+ * BOARD_LED_PIN.  Its length is BOARD_NR_USED_PINS.
+ */
+extern const uint8 boardUsedPins[];
+
+/**
+ * @brief Generic board initialization function.
+ *
+ * This function is called before main().  It ensures that the clocks
+ * and peripherals are configured properly for use with wirish, then
+ * calls boardInit().
+ *
+ * @see boardInit()
+ */
 void init(void);
 
 /**
@@ -78,6 +109,16 @@ void init(void);
  */
 extern void boardInit(void);
 
+/**
+ * @brief Test if a pin is used for a special purpose on your board.
+ * @param pin Pin to test
+ * @return true if the given pin is in boardUsedPins, and false otherwise.
+ * @see boardUsedPins
+ */
+bool boardUsesPin(uint8 pin);
+
+/* Include the appropriate private header from boards/: */
+
 #ifdef BOARD_maple
 #include "boards/maple.h"
 #elif defined(BOARD_maple_native)
diff --git a/wirish/boards/maple.cpp b/wirish/boards/maple.cpp
index ba2261b..5122290 100644
--- a/wirish/boards/maple.cpp
+++ b/wirish/boards/maple.cpp
@@ -40,7 +40,7 @@
 void boardInit(void) {
 }
 
-stm32_pin_info PIN_MAP[NR_GPIO_PINS] = {
+extern const stm32_pin_info PIN_MAP[BOARD_NR_GPIO_PINS] = {
 
     /* Top header */
 
@@ -91,4 +91,16 @@ stm32_pin_info PIN_MAP[NR_GPIO_PINS] = {
     {GPIOC,   NULL, NULL,  9, 0, ADCx}  /* D38/PC9 (BUT) */
 };
 
+extern const uint8 boardPWMPins[] __FLASH__ = {
+    0, 1, 2, 3, 5, 6, 7, 8, 9, 11, 12, 14, 24, 25, 27, 28
+};
+
+extern const uint8 boardADCPins[] __FLASH__ = {
+    0, 1, 2, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28
+};
+
+extern const uint8 boardUsedPins[] __FLASH__ = {
+    BOARD_LED_PIN, BOARD_BUTTON_PIN
+};
+
 #endif
diff --git a/wirish/boards/maple.h b/wirish/boards/maple.h
index 519698b..1867de8 100644
--- a/wirish/boards/maple.h
+++ b/wirish/boards/maple.h
@@ -42,7 +42,7 @@
 #define BOARD_LED_PIN           13
 
 /* Number of USARTs/UARTs whose pins are broken out to headers */
-#define NR_USARTS               3
+#define BOARD_NR_USARTS         3
 
 /* Default USART pin numbers (not considering AFIO remap) */
 #define BOARD_USART1_TX_PIN     7
@@ -53,7 +53,17 @@
 #define BOARD_USART3_RX_PIN     30
 
 /* Total number of GPIO pins that are broken out to headers and
-   intended for general use. */
-#define NR_GPIO_PINS            39
+ * intended for general use. */
+#define BOARD_NR_GPIO_PINS      39
+
+/* Number of pins capable of PWM output */
+#define BOARD_NR_PWM_PINS       16
+
+/* Number of pins capable of ADC conversion */
+#define BOARD_NR_ADC_PINS       15
+
+/* Number of pins already connected to external hardware.  For Maple,
+ * these are just BOARD_LED_PIN and BOARD_BUTTON_PIN. */
+#define BOARD_NR_USED_PINS       2
 
 #endif
diff --git a/wirish/boards/maple_RET6.cpp b/wirish/boards/maple_RET6.cpp
index 962affc..fd67459 100644
--- a/wirish/boards/maple_RET6.cpp
+++ b/wirish/boards/maple_RET6.cpp
@@ -37,7 +37,7 @@
 void boardInit(void) {
 }
 
-stm32_pin_info PIN_MAP[NR_GPIO_PINS] = {
+extern const stm32_pin_info PIN_MAP[BOARD_NR_GPIO_PINS] = {
 
     /* Top header */
 
@@ -88,4 +88,16 @@ stm32_pin_info PIN_MAP[NR_GPIO_PINS] = {
     {GPIOC, TIMER8, NULL,  9, 4, ADCx}  /* D38/PC9 (BUT) */
 };
 
+extern const uint8 boardPWMPins[BOARD_NR_PWM_PINS] __FLASH__ = {
+    0, 1, 2, 3, 5, 6, 7, 8, 9, 11, 12, 14, 24, 25, 27, 28
+};
+
+extern const uint8 boardADCPins[BOARD_NR_ADC_PINS] __FLASH__ = {
+    0, 1, 2, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28
+};
+
+extern const uint8 boardUsedPins[BOARD_NR_USED_PINS] __FLASH__ = {
+    BOARD_LED_PIN, BOARD_BUTTON_PIN
+};
+
 #endif
diff --git a/wirish/boards/maple_RET6.h b/wirish/boards/maple_RET6.h
index 63510c0..d91a4de 100644
--- a/wirish/boards/maple_RET6.h
+++ b/wirish/boards/maple_RET6.h
@@ -47,8 +47,7 @@
 #define BOARD_LED_PIN           13
 
 /* Note: UART4 and UART5 have pins which aren't broken out :( */
-#define NR_USARTS               3
-
+#define BOARD_NR_USARTS         3
 #define BOARD_USART1_TX_PIN     7
 #define BOARD_USART1_RX_PIN     8
 #define BOARD_USART2_TX_PIN     1
@@ -56,6 +55,9 @@
 #define BOARD_USART3_TX_PIN     29
 #define BOARD_USART3_RX_PIN     30
 
-#define NR_GPIO_PINS            39
+#define BOARD_NR_GPIO_PINS      39
+#define BOARD_NR_PWM_PINS       16
+#define BOARD_NR_ADC_PINS       15
+#define BOARD_NR_USED_PINS      2
 
 #endif
diff --git a/wirish/boards/maple_mini.cpp b/wirish/boards/maple_mini.cpp
index 66a0997..cd2827d 100644
--- a/wirish/boards/maple_mini.cpp
+++ b/wirish/boards/maple_mini.cpp
@@ -41,7 +41,7 @@ void boardInit(void) {
     afio_mapr_swj_config(AFIO_MAPR_SWJ_NO_JTAG_NO_SW);
 }
 
-stm32_pin_info PIN_MAP[NR_GPIO_PINS] = {
+extern const stm32_pin_info PIN_MAP[BOARD_NR_GPIO_PINS] = {
 
     /* Top header */
 
@@ -84,4 +84,19 @@ stm32_pin_info PIN_MAP[NR_GPIO_PINS] = {
     {GPIOB, TIMER3, ADC1,  1, 4,    9}, /* D33/PB1 */
 };
 
+extern const uint8 boardPWMPins[BOARD_NR_PWM_PINS] __FLASH__ = {
+    3, 4, 5, 8, 9, 10, 11, 15, 16, 25, 26, 27
+};
+
+extern const uint8 boardADCPins[BOARD_NR_ADC_PINS] __FLASH__ = {
+    3, 4, 5, 6, 7, 8, 9, 10, 11, 33  // NB 33 is LED
+};
+
+#define USB_DP 23
+#define USB_DM 24
+
+extern const uint8 boardUsedPins[BOARD_NR_USED_PINS] __FLASH__ = {
+    BOARD_LED_PIN, BOARD_BUTTON_PIN, USB_DP, USB_DM
+};
+
 #endif
diff --git a/wirish/boards/maple_mini.h b/wirish/boards/maple_mini.h
index bfb92a5..8b7ae64 100644
--- a/wirish/boards/maple_mini.h
+++ b/wirish/boards/maple_mini.h
@@ -46,8 +46,7 @@
 #define BOARD_BUTTON_PIN          32
 #define BOARD_LED_PIN             33
 
-#define NR_USARTS                 3
-
+#define BOARD_NR_USARTS           3
 #define BOARD_USART1_TX_PIN       26
 #define BOARD_USART1_RX_PIN       25
 #define BOARD_USART2_TX_PIN       9
@@ -55,6 +54,9 @@
 #define BOARD_USART3_TX_PIN       1
 #define BOARD_USART3_RX_PIN       0
 
-#define NR_GPIO_PINS              34
+#define BOARD_NR_GPIO_PINS        34
+#define BOARD_NR_PWM_PINS         12
+#define BOARD_NR_ADC_PINS         10
+#define BOARD_NR_USED_PINS         4
 
 #endif
diff --git a/wirish/boards/maple_native.cpp b/wirish/boards/maple_native.cpp
index 75c6a2d..2813e91 100644
--- a/wirish/boards/maple_native.cpp
+++ b/wirish/boards/maple_native.cpp
@@ -39,7 +39,7 @@ void boardInit(void) {
     initNativeSRAM();
 }
 
-stm32_pin_info PIN_MAP[NR_GPIO_PINS] = {
+extern const stm32_pin_info PIN_MAP[BOARD_NR_GPIO_PINS] = {
 
     /* Top header */
 
@@ -152,4 +152,18 @@ stm32_pin_info PIN_MAP[NR_GPIO_PINS] = {
     {GPIOD,   NULL, NULL, 10, 0, ADCx}  /* D99/PD10 */
 };
 
+extern const uint8 boardPWMPins[BOARD_NR_PWM_PINS] __FLASH__ = {
+    12, 13, 14, 15, 22, 23, 24, 25, 37, 38, 45, 46, 47, 48, 49, 50, 53, 54
+};
+
+extern const uint8 boardADCPins[BOARD_NR_ADC_PINS] __FLASH__ = {
+    6, 7, 8, 9, 10, 11, 39, 40, 41, 42, 43, 45, 46, 47, 48, 49, 50, 51, 52, 53,
+    54
+};
+
+/* FIXME! see comment by BOARD_NR_USED_PINS in maple_native.h */
+extern const uint8 boardUsedPins[BOARD_NR_USED_PINS] __FLASH__ = {
+    BOARD_LED_PIN, BOARD_BUTTON_PIN
+};
+
 #endif
diff --git a/wirish/boards/maple_native.h b/wirish/boards/maple_native.h
index 21fc480..4e3ee82 100644
--- a/wirish/boards/maple_native.h
+++ b/wirish/boards/maple_native.h
@@ -43,11 +43,10 @@
 #define CYCLES_PER_MICROSECOND  72
 #define SYSTICK_RELOAD_VAL      71999
 
-#define BOARD_LED_PIN           D21
-#define BOARD_BUTTON_PIN        D18
-
-#define NR_USARTS               5
+#define BOARD_LED_PIN           21
+#define BOARD_BUTTON_PIN        18
 
+#define BOARD_NR_USARTS         5
 #define BOARD_USART1_TX_PIN     25
 #define BOARD_USART1_RX_PIN     26
 #define BOARD_USART2_TX_PIN     51
@@ -59,6 +58,12 @@
 #define BOARD_UART5_TX_PIN      20
 #define BOARD_UART5_RX_PIN      28
 
-#define NR_GPIO_PINS            100
+#define BOARD_NR_GPIO_PINS      100
+#define BOARD_NR_PWM_PINS       18
+#define BOARD_NR_ADC_PINS       21
+/* FIXME! this isn't true at all; almost all of the triple header pins
+ * are used by the FSMC by default.  Fix this (and the corresponding
+ * boardUsedPins definition in maple_native.cpp) by QA time. */
+#define BOARD_NR_USED_PINS      2
 
 #endif
diff --git a/wirish/comm/HardwareSerial.cpp b/wirish/comm/HardwareSerial.cpp
index 97a5ec3..8398878 100644
--- a/wirish/comm/HardwareSerial.cpp
+++ b/wirish/comm/HardwareSerial.cpp
@@ -32,10 +32,12 @@
 #include "HardwareSerial.h"
 #include "usart.h"
 
+// FIXME: High density device ports, usages of BOARD_USARTx_yX_PIN
+// instead of holding onto a gpio_dev, tx_pin, rx_pin, timer_dev, and
+// channel_num -- that stuff is all in the PIN_MAP.
 HardwareSerial Serial1(USART1, 4500000UL, GPIOA,  9, 10, TIMER1, 2);
 HardwareSerial Serial2(USART2, 2250000UL, GPIOA,  2,  3, TIMER2, 3);
 HardwareSerial Serial3(USART3, 2250000UL, GPIOB, 10, 11,   NULL, 0);
-// TODO: High density device ports
 
 HardwareSerial::HardwareSerial(uint8 usart_num,
                                uint32 max_baud,
diff --git a/wirish/ext_interrupts.cpp b/wirish/ext_interrupts.cpp
index f9ccd39..557fffd 100644
--- a/wirish/ext_interrupts.cpp
+++ b/wirish/ext_interrupts.cpp
@@ -43,7 +43,7 @@ static inline exti_trigger_mode exti_out_mode(ExtIntTriggerMode mode);
  * @see ExtIntTriggerMode
  */
 void attachInterrupt(uint8 pin, voidFuncPtr handler, ExtIntTriggerMode mode) {
-    if (pin >= NR_GPIO_PINS || !handler) {
+    if (pin >= BOARD_NR_GPIO_PINS || !handler) {
         return;
     }
 
@@ -60,7 +60,7 @@ void attachInterrupt(uint8 pin, voidFuncPtr handler, ExtIntTriggerMode mode) {
  * @param pin Pin number to detach any interrupt from.
  */
 void detachInterrupt(uint8 pin) {
-    if (pin >= NR_GPIO_PINS) {
+    if (pin >= BOARD_NR_GPIO_PINS) {
         return;
     }
 
diff --git a/wirish/pwm.cpp b/wirish/pwm.cpp
index 4c803d2..bf69bfb 100644
--- a/wirish/pwm.cpp
+++ b/wirish/pwm.cpp
@@ -34,7 +34,7 @@
 
 void pwmWrite(uint8 pin, uint16 duty_cycle) {
     timer_dev *dev = PIN_MAP[pin].timer_device;
-    if (pin >= NR_GPIO_PINS || dev == NULL || dev->type == TIMER_BASIC) {
+    if (pin >= BOARD_NR_GPIO_PINS || dev == NULL || dev->type == TIMER_BASIC) {
         return;
     }
 
diff --git a/wirish/wirish_digital.cpp b/wirish/wirish_digital.cpp
index 115e91e..9b9f175 100644
--- a/wirish/wirish_digital.cpp
+++ b/wirish/wirish_digital.cpp
@@ -33,7 +33,7 @@ void pinMode(uint8 pin, WiringPinMode mode) {
     gpio_pin_mode outputMode;
     boolean pwm = false;
 
-    if (pin >= NR_GPIO_PINS) {
+    if (pin >= BOARD_NR_GPIO_PINS) {
         return;
     }
 
@@ -83,7 +83,7 @@ void pinMode(uint8 pin, WiringPinMode mode) {
 
 
 uint32 digitalRead(uint8 pin) {
-    if (pin >= NR_GPIO_PINS) {
+    if (pin >= BOARD_NR_GPIO_PINS) {
         return 0;
     }
 
@@ -92,7 +92,7 @@ uint32 digitalRead(uint8 pin) {
 }
 
 void digitalWrite(uint8 pin, uint8 val) {
-    if (pin >= NR_GPIO_PINS) {
+    if (pin >= BOARD_NR_GPIO_PINS) {
         return;
     }
 
@@ -100,14 +100,14 @@ void digitalWrite(uint8 pin, uint8 val) {
 }
 
 void togglePin(uint8 pin) {
-    if (pin >= NR_GPIO_PINS) {
+    if (pin >= BOARD_NR_GPIO_PINS) {
         return;
     }
 
     gpio_toggle_bit(PIN_MAP[pin].gpio_device, PIN_MAP[pin].gpio_bit);
 }
 
-#define BUTTON_DEBOUNCE_DELAY 10
+#define BUTTON_DEBOUNCE_DELAY 1
 
 uint8 isButtonPressed() {
     if (digitalRead(BOARD_BUTTON_PIN)) {
diff --git a/wirish/wirish_types.h b/wirish/wirish_types.h
index 7d6e31a..475f470 100644
--- a/wirish/wirish_types.h
+++ b/wirish/wirish_types.h
@@ -30,6 +30,7 @@
  * @brief  Wirish library type definitions.
  */
 
+#include "libmaple_types.h"
 #include "gpio.h"
 #include "timer.h"
 #include "adc.h"
@@ -56,4 +57,6 @@ typedef struct stm32_pin_info {
     uint8 adc_channel;          /**< Pin ADC channel, or ADCx if none. */
 } stm32_pin_info;
 
+#define __FLASH__ __attr_flash
+
 #endif