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, 20 insertions, 13 deletions

diff --git a/docs/source/lang/api/analogread.rst b/docs/source/lang/api/analogread.rst
index 35c6fbc..7099b69 100644
--- a/docs/source/lang/api/analogread.rst
+++ b/docs/source/lang/api/analogread.rst
@@ -35,6 +35,8 @@ have to do this once, so it's usually done in :ref:`lang-setup`\ ).
 Parameter Discussion
 --------------------
 
+.. FIXME generalize Maple-specific information
+
 The pin parameter is the number of the analog input pin to read from.
 Header pins on the Maple with ADC functionality (marked as "AIN" on
 the silkscreen) are:
@@ -49,24 +51,25 @@ Note
 ----
 
 If the analog input pin is not connected to anything, the value
-returned by analogRead() will fluctuate based on a number of factors
-(e.g. the values of the other analog inputs, how close your hand is to
-the board, etc.) in a seemingly random way.
+returned by ``analogRead()`` will fluctuate due to a number of reasons
+(like the values of the other analog inputs, how close your hand is to
+the board, etc.) in a "random" way.
 
 
 Example
 -------
 
- ::
+::
 
+    int analogPin = 3;     // Potentiometer wiper (middle terminal) connected
+                           // to analog pin 3. outside leads to ground and +3.3V.
+                           // You may have to change this value if your board
+                           // cannot perform ADC conversion on pin 3.
 
-    int analogPin = 3;     // potentiometer wiper (middle terminal) connected
-                           // to analog pin 3. outside leads to ground and +3.3V
     int val = 0;           // variable to store the value read
 
     void setup() {
       pinMode(analogPin, INPUT_ANALOG); // set up pin for analog input
-      SerialUSB.begin();                // set up usb virtual COM port
     }
 
     void loop() {
@@ -97,23 +100,27 @@ shift <lang-bitshift>` the value of a Maple readout by 2, like so::
     // be aware that you're losing a lot of precision if you do this
     int adc_reading = analogRead(pin) >> 2;
 
+.. FIXME Mention Native can do analogReference(), when it's time
+
 On the Arduino, the input range and resolution can be changed using
 their implementation of `analogReference()
 <http://arduino.cc/en/Reference/AnalogReference>`_\ . Because of the
 way its hardware (as of Rev 5) was designed, it's not possible to
 implement analogReference on the Maple, so this function doesn't
 exist.  If your inputs lie in a different voltage range than 0V--3.3V,
-you'll need to bring them into that range before using analogRead.
-Some basic tools to accomplish this are `resistor dividers
-<http://en.wikipedia.org/wiki/Voltage_divider>`_ and `Zener diodes
+you'll need to bring them into that range before using
+``analogRead()``.  Some basic tools to accomplish this are `resistor
+dividers <http://en.wikipedia.org/wiki/Voltage_divider>`_ and `Zener
+diodes
 <http://en.wikipedia.org/wiki/Voltage_source#Zener_voltage_source>`_\
-. However, opamps and other powered components can also be used if
-greater precision is required.
+. However, `operational amplifiers
+<http://en.wikipedia.org/wiki/Operational_amplifier>`_ and other
+powered components can also be used if greater precision is required.
 
 See also
 --------
 
-- :ref:`ADC note <adc>`
+- :ref:`ADC tutorial <adc>`
 - `(Arduino) Tutorial: Analog Input Pins <http://arduino.cc/en/Tutorial/AnalogInputPins>`_
 
 .. include:: cc-attribution.txt