Better debug port support.

- gpio.h: afio_mapr_swj_config() renamed afio_cfg_debug_ports()

- [new] wirish_debug.h: disableDebugPorts(), enableDebugPorts()

- Maple, Maple Native, and Maple RET6 PIN_MAPs are now larger by 5,
  have mappings for the extra JTAG/SW pins.

  Documentation was updated appropriately.

5 files changed, 129 insertions, 75 deletions

diff --git a/docs/source/hardware/maple.rst b/docs/source/hardware/maple.rst
index 44a5238..1fa4f3f 100644
--- a/docs/source/hardware/maple.rst
+++ b/docs/source/hardware/maple.rst
@@ -40,7 +40,7 @@ Identifying your Rev
 We went through three versions ("Revs") of the Maple hardware: Rev 1,
 Rev 3, and Rev 5 [#frev2_4]_; Rev 5, the final design, is currently on
 sale.  The following sections will help you to help you identify your
-Rev.  Known issues are listed in the :ref:`errata <maple-errata>`.
+Rev.
 
 Rev 5
 ^^^^^
@@ -123,46 +123,38 @@ at the command line with ::
 
     $ git clone git://github.com/leaflabs/maple.git
 
-.. _maple-errata:
+.. _maple-failure-modes:
 
-Errata
-------
-
-This section lists known issues and warnings for each revision of the
-Maple board. The failure modes aren't design errors, but are easy ways
-to break or damage your board permanently. For a list of differences
-between the Maple and Arduinos, see the :ref:`Arduino Compatibility
-reference <arduino-compatibility>`.
-
-The errata are grouped by Maple version ("Rev").
-
-Maple Rev 5
-^^^^^^^^^^^
-
-Known issues:
+Failure Modes
+-------------
 
-* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the
-  corresponding "AIN" is missing from its silkscreen.
-
-* **GPIO 39-43 not configured**: this is really more of a software
-  "TODO" item.  Some of the JTAG header pins are numbered 39-43. These
-  STM32 pins are indeed fully functional :ref:`GPIO <gpio>` when a
-  :ref:`JTAG <jtag>` device is not connected, but we have not enabled
-  them in software and thus they can not be accessed with the regular
-  :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions.
-
-Potential failure modes:
+The following known failure modes apply to all Maple versions.  The
+failure modes aren't design errors, but are easy ways to break or
+damage your board permanently.
 
 * **High voltage on non-tolerant pins**: not all header pins are 5V
   compatible; so e.g. connecting certain serial devices in the wrong
   way could over-voltage the pins.  The :ref:`Pin-Mapping Mega Table
   <pin-mapping-mega-table>` details which pins are 5V-tolerant.
 
-Maple Rev 3
-^^^^^^^^^^^
+Errata
+------
+
+This section lists known issues and warnings for each revision of the
+Maple board.
 
+Rev 5
+^^^^^
 Known issues:
 
+* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but on
+  boards sold in during Fall 2010, the corresponding "AIN" is missing
+  from its silkscreen.  This mistake was fixed in later manufacturing
+  runs.
+
+Rev 3
+^^^^^
+
 * **Bad/Sticky Buttons**: a number of Rev 3 boards sold in May-June 2010
   have questionable RESET and BUT buttons.
 
@@ -180,7 +172,7 @@ Known issues:
   remover we used is "Precision Electronics Cleaner" from RadioShack,
   which is "Safe on most plastics" and contains Dipropylene glycol
   monomethyl ether, hydrotreated heavy naphtha, dipropylene glycol
-  methyl ether acetate (really?), and carbon dioxide.
+  methyl ether acetate, and carbon dioxide.
 
 * **Resistors on pins 0 and 1**: these header pins, which are RX/TX on
   USART2 (:ref:`Serial2 <lang-serial>`), have resistors in-line
@@ -192,13 +184,6 @@ Known issues:
   designs, where they appear to protect the USB-Serial converter from
   TTL voltage on the headers.
 
-* **GPIO 39-43 not configured**: this is really more of a software
-  "TODO" item.  Some of the JTAG header pins are numbered 39-43. These
-  STM32 pins are indeed fully functional :ref:`GPIO <gpio>` when the a
-  :ref:`JTAG <jtag>` device is not connected, but we have not enabled
-  them in software and thus they can not be accessed with the regular
-  :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions.
-
 * **Silkscreen Errors**: the silkscreen on the bottom indicated PWM
   functionality on pin 25 and listen the external header GND pin as
   number 38 (actually 38 is connected to the BUT button). We manually
@@ -207,17 +192,8 @@ Known issues:
 * **PWM Marketing Mistake**: We originally sold the Maple advertising
   22 channels of 16-bit hardware PWM; actually the Maple only has 15.
 
-Potential failure modes:
-
-* **TTL voltage on non-tolerant pins**: not all header pins are 5V
-  compatible; connecting certain serial devices in the wrong way could
-  over voltage the pins.  The :ref:`Pin-Mapping Mega Table
-  <pin-mapping-mega-table>` details which pins are 5V-tolerant.
-
-Maple Rev 1
-^^^^^^^^^^^
-
-Known issues:
+Rev 1
+^^^^^
 
 * **ADC noise**: generally very high, in particular when the USB port
   is being used for communications (including keep-alive pings when
@@ -248,14 +224,7 @@ Known issues:
   <http://forums.leaflabs.com/topic.php?id=32#post-126>`_.
 
 * **PWM Marketing Mistake**: We originally sold the Maple advertising
-  22 channels of 16-bit hardware PWM; actually the Maple only has 15.
-
-Potential failure modes:
-
-* **TTL voltage on non-tolerant pins**: not all header pins are 5v
-  compatible; connecting certain serial devices in the wrong way could
-  over voltage the pins. The :ref:`Pin-Mapping Mega Table
-  <pin-mapping-mega-table>` details which pins are 5V-tolerant.
+  22 channels of 16-bit hardware PWM; the correct number is 15.
 
 Recommended Reading
 -------------------
diff --git a/docs/source/jtag.rst b/docs/source/jtag.rst
index 858021e..cc6d34a 100644
--- a/docs/source/jtag.rst
+++ b/docs/source/jtag.rst
@@ -1,11 +1,12 @@
+.. highlight:: cpp
+
 .. _jtag:
 
 ======
  JTAG
 ======
 
-.. TODO update adapter schematic, add information on using it with our
-.. devices.
+.. FIXME update adapter schematic, add better information
 
 JTAG is an interface for low-level debugging of digital devices. It
 gives instruction by instruction control over the microprocessor and
@@ -37,32 +38,36 @@ Wiring Diagram
    to connect a standard 20-pin ARM JTAG device to the 8-pin JTAG port
    on the Maple.
 
-The Maple has holes for a 8-pin JTAG header but that header is not
-soldered on by default. If you know ahead of time that you'll be
-needing it, and you order `straight from LeafLabs
-<http://leaflabs.com/store/>`_, add a comment to your order and we can
-probably solder one on for no charge.  Otherwise, you can simply
-attach standard 0.1" pitch male header pins (either the exact 4x2
-block or two 4-pin pieces of breakaway straight header). For a one-off
-usage hack, the header can be jammed in the holes and twisted to
-ensure electrical contact.
+The Maple has holes for a 8-pin JTAG header, but that header is not
+soldered on.  To use JTAG, simply solder on standard 0.1" pitch male
+header pins (either the exact 4 by 2 block, or two 4-pin pieces of
+straight breakaway header).
 
 Compatible Devices
 ------------------
 
 We have had good experience with the `Olimex ARM-USB-OCD
 <http://www.olimex.com/dev/arm-usb-ocd.html>`_ device, which costs
-about 55 euro plus shipping (as of November 2010).
+about €55 plus shipping (as of April 2011).
+
+Function Reference
+------------------
+
+You can disable or enable the JTAG and Serial Wire debugging ports in
+software using the ``disableDebugPorts()`` and ``enableDebugPorts()``
+functions.
+
+* :ref:`lang-disabledebugports`
+* :ref:`lang-enabledebugports`
 
 Recommended Reading
 -------------------
 
 * `Wikipedia Article on Joint Test Action Group (JTAG) <http://en.wikipedia.org/wiki/Joint_Test_Action_Group>`_
-* `STM32/gdb/OpenOCD HOWTO <http://fun-tech.se/stm32/OpenOCD/gdb.php>`_
+* `STM32, GDB, OpenOCD How To <http://fun-tech.se/stm32/OpenOCD/gdb.php>`_
 * STMicro documentation for STM32F103RB microcontroller:
 
   * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf)
   * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf)
-* There's a `thread on JTAG
-  <http://forums.leaflabs.com/topic.php?id=536>`_ in our `forum`_
-  which you may find useful.
+* `LeafLabs Wiki JTAG How To <http://wiki.leaflabs.com/index.php?title=Maple_JTAG_How_To>`_
+* `Forum thread on JTAG <http://forums.leaflabs.com/topic.php?id=536>`_
diff --git a/docs/source/lang/api/board-values.rst b/docs/source/lang/api/board-values.rst
index d6d78f6..e274163 100644
--- a/docs/source/lang/api/board-values.rst
+++ b/docs/source/lang/api/board-values.rst
@@ -84,8 +84,25 @@ Constants
     * ``BOARD_NR_USARTS``: Number of serial ports on the board.  This
       number includes UARTs 4 and 5 if they are available.
 
+.. _lang-board-values-debug:
+
+- Debug (JTAG, SW-Debug) related constants: ``BOARD_JTMS_SWDIO_PIN``,
+  ``BOARD_JTCK_SWCLK_PIN``, ``BOARD_JTDI_PIN``, ``BOARD_JTDO_PIN``,
+  and ``BOARD_NJTRST_PIN``.
+
+  These constants are the pin numbers for :ref:`GPIOs <gpio>` used by
+  the :ref:`jtag` and Serial-Wire Debug peripherals.  Except for the
+  Maple Mini, these pins are usually reserved for special purposes by
+  default (i.e., they are in :ref:`boardUsedPins
+  <lang-board-values-used-pins>`).  However, they can be used as
+  ordinary GPIOs if you call the :ref:`lang-disabledebugports`
+  function.  (Be careful with this on the Maple, as writing to
+  ``BOARD_NJTRST_PIN`` may cause your board to reset!).
+
 .. _lang-board-values-pwm-pins:
+
 .. _lang-board-values-adc-pins:
+
 .. _lang-board-values-used-pins:
 
 Pin Arrays
@@ -94,8 +111,7 @@ Pin Arrays
 Some :ref:`arrays <lang-array>` of pin numbers are available which you
 can use to find out certain important information about a given pin.
 
-.. TODO add links to the board-specific hardware information on what
-.. are in these arrays
+.. TODO [0.1.0] links to board-specific hardware information
 
 - ``boardPWMPins``: Pin numbers of each pin capable of :ref:`PWM
   <pwm>` output, using :ref:`pwmWrite() <lang-pwmwrite>`.  The total
@@ -159,3 +175,5 @@ See Also
 - :ref:`lang-toggleled`
 - :ref:`lang-analogread`
 - :ref:`lang-pwmwrite`
+- :ref:`lang-enabledebugports`
+- :ref:`lang-disabledebugports`
diff --git a/docs/source/lang/api/disabledebugports.rst b/docs/source/lang/api/disabledebugports.rst
new file mode 100644
index 0000000..43ac337
--- /dev/null
+++ b/docs/source/lang/api/disabledebugports.rst
@@ -0,0 +1,31 @@
+.. highlight:: cpp
+
+.. _lang-disabledebugports:
+
+disableDebugPorts()
+===================
+
+Used to disable the JTAG and Serial Wire debugging ports.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: disableDebugPorts
+
+Example
+-------
+
+ ::
+
+    void setup() {
+        disableDebugPorts();
+    }
+
+    void loop() {
+        // Now you can use the debug port pins as ordinary pins
+    }
+
+See Also
+--------
+
+* :ref:`lang-enabledebugports`
diff --git a/docs/source/lang/api/enabledebugports.rst b/docs/source/lang/api/enabledebugports.rst
new file mode 100644
index 0000000..bee2b0a
--- /dev/null
+++ b/docs/source/lang/api/enabledebugports.rst
@@ -0,0 +1,31 @@
+.. highlight:: cpp
+
+.. _lang-enabledebugports:
+
+enableDebugPorts()
+==================
+
+Used to enable the JTAG and Serial Wire debugging ports.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: enableDebugPorts
+
+Example
+-------
+
+ ::
+
+    void setup() {
+        enableDebugPorts();
+        // Now you can debug using JTAG and SW-Debug
+    }
+
+    void loop() {
+    }
+
+See Also
+--------
+
+* :ref:`lang-disabledebugports`