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, 34 insertions, 19 deletions

diff --git a/docs/source/arm-gcc.rst b/docs/source/arm-gcc.rst
index ef745f5..7ecb5d4 100644
--- a/docs/source/arm-gcc.rst
+++ b/docs/source/arm-gcc.rst
@@ -4,12 +4,11 @@
 GCC for Maple
 =============
 
-This document provides notes on the current usage of
-``arm-none-eabi-gcc``, the `CodeSourcery <http://codesourcery.com>`_
-version of the GNU `GCC <http://gcc.gnu.org/>`_ compilers used to
-compile programs for the Maple.  It is not intended as a reference
-manual for GCC; such manuals are available `elsewhere
-<http://gcc.gnu.org/>`_.
+This document provides notes on using of ``arm-none-eabi-gcc``, the
+`CodeSourcery <http://codesourcery.com>`_ version of the GNU `GCC
+<http://gcc.gnu.org/>`_ compilers used for the Maple boards.  It is
+not intended as a reference manual for GCC; such manuals are available
+`elsewhere <http://gcc.gnu.org/>`_.
 
 Obtaining ``arm-none-eabi-gcc``
 -------------------------------
@@ -17,21 +16,24 @@ Obtaining ``arm-none-eabi-gcc``
 Recent versions of ``arm-none-eabi-gcc`` and associated tools are
 included with the :ref:`Maple IDE <ide>`.
 
-Users who wish to use ``arm-none-eabi-gcc`` in concert with a standard
-Unix toolchain are referred to our :ref:`unix-toolchain` reference,
-which describes how to set up such an environment.
+Users who wish to use ``arm-none-eabi-gcc`` directly, along with a
+standard Unix Make-based toolchain, should read the
+:ref:`unix-toolchain`, which describes how to set up such an
+environment.
 
-LeafLabs mirrors some of the more recent versions of the compiler
-under http://static.leaflabs.com/pub/codesourcery/\ , including
-versions for OS X, win32, and 32-bit Linux.
+LeafLabs maintains `mirrors
+<http://static.leaflabs.com/pub/codesourcery/>`_ for some of the more
+recent versions of the compiler, including versions for OS X, Win32,
+and 32-bit Linux.
 
 Compiler Flags Used by libmaple
 -------------------------------
 
 This section documents the flags passed to ``arm-none-eabi-gcc`` by
-the :ref:`Maple IDE <ide>` and the default Makefile provided with
-:ref:`libmaple <unix-toolchain>`.  The information in this section is
-subject to change without notice.
+the :ref:`Maple IDE <ide>` and the default Makefile provided with the
+:ref:`Unix toolchain <unix-toolchain>`.  The information in this
+section is subject to change between :ref:`libmaple <libmaple>`
+releases.
 
 .. highlight:: sh
 
@@ -40,7 +42,8 @@ The following flags are among those passed to the C compiler::
     -Os -g -mcpu=cortex-m3 -mthumb -march=armv7-m -nostdlib
     -ffunction-sections -fdata-sections -Wl,--gc-sections
 
-The following flags are among those passed to the C++ compiler::
+In addition to those flags just given for the C compiler, the
+following flags are among those passed to the C++ compiler::
 
     -fno-rtti -fno-exceptions -Wall
 
@@ -52,6 +55,15 @@ The following flags are among those passed to the assembler::
 
 .. _arm-gcc-avr-gcc:
 
+Using the C Standard Library
+----------------------------
+
+By default (under both the :ref:`Maple IDE <ide>` and the :ref:`Unix
+toolchain <unix-toolchain>`), ``arm-none-eabi-gcc`` is configured to
+link against `newlib <http://sourceware.org/newlib/>`_, a C standard
+library intended for use with embedded applications.  You are free to
+include of any of its headers.
+
 Switching from AVR-GCC
 ----------------------
 
@@ -63,8 +75,11 @@ including Arduino) for use on the Maple.
 .. _arm-gcc-attribute-flash:
 
 - Replacing ``PROGMEM``: You can direct the linker script provided
-  with libmaple to store a variable in flash by using
-  ``__attribute__((section (".USER_FLASH")))``, like so::
+  with libmaple to store a variable in Flash (instead of RAM) by using
+  the libmaple macro ``__FLASH__``, like so::
 
-      uint32 arr[] __attribute__((section (".USER_FLASH"))) = {...};
+      uint32 array[] __FLASH__ = {0, 1, 2};
 
+  Be aware, however, that if you do that, you can only store values
+  which are compile-time constants, and that if you attempt to change
+  a variable stored in Flash, your program will crash.