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.

1 files changed, 10 insertions, 16 deletions

diff --git a/docs/source/lang/api/constants.rst b/docs/source/lang/api/constants.rst
index 2e968e7..c5a7c0c 100644
--- a/docs/source/lang/api/constants.rst
+++ b/docs/source/lang/api/constants.rst
@@ -293,23 +293,16 @@ exponent indicators.  Some examples are given in the following table:
 Board-Specific Constants
 ------------------------
 
-This section documents constants whose value might change across
-different LeafLabs boards.  You can use these constants to help ensure
-that your code will be portable across different boards.
+There are several :ref:`board-specific constants <lang-board-values>`
+whose value depends on which LeafLabs board you have.  If you use
+them, it will help make sure that your code will work well on all
+LeafLabs boards, not just the one you have.  This will make it much
+easier to share your code with others.
 
-.. TODO replace "upcoming" when Mini, Native come out
-
-.. _lang-constants-led:
-
-- ``BOARD_LED_PIN``: the number of the pin which connects to the
-  built-in LED.  On the Maple, this is pin 13, but it's not guaranteed
-  to be the same in upcoming boards like the Maple Mini.
-
-.. _lang-constants-but:
-
-- ``BOARD_BUTTON_PIN``: the number of the pin which connects to the
-  built-in button (labeled "BUT").  On the Maple, this is pin 38, but
-  it's not guaranteed to be the same in other boards.
+For example, the pin number connected to the board's built-in LED is
+different on the different boards, but the board-specific constant
+:ref:`BOARD_LED_PIN <lang-board-values-led>` will always be the
+correct value for each board.
 
 See Also
 --------
@@ -325,5 +318,6 @@ See Also
 - :ref:`unsigned long long <lang-unsignedlonglong>`
 - :ref:`float <lang-float>`
 - :ref:`double <lang-double>`
+- :ref:`Board-Specific Values <lang-board-values>`
 
 .. include:: cc-attribution.txt