From 95af192c99459c56bb30763afd93582a524efc3a Mon Sep 17 00:00:00 2001
From: Marti Bolivar <mbolivar@leaflabs.com>
Date: Mon, 25 Apr 2011 21:23:00 -0400
Subject: 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.
---
 docs/source/lang/api/board-values.rst      | 22 +++++++++++++++++++--
 docs/source/lang/api/disabledebugports.rst | 31 ++++++++++++++++++++++++++++++
 docs/source/lang/api/enabledebugports.rst  | 31 ++++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+), 2 deletions(-)
 create mode 100644 docs/source/lang/api/disabledebugports.rst
 create mode 100644 docs/source/lang/api/enabledebugports.rst

(limited to 'docs/source/lang/api')

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`
-- 
cgit v1.2.3