merge libmaple docs ("leaflabs-docs") into ./docs

In the past, libample documentation was forked out of this repository
because the documentation had increased in scope. For the librambutan,
and the rambutan project in general, we will try to keep documentation
closer to the source code, so the librambutan-specific documentation
should live here. Other sections of leaflabs-docs will be culled in a
following commit.

This merge attempts to maintain history by using a subtree strategy.
Followed directions at:

    http://nuclearsquid.com/writings/subtree-merging-and-you/

Full history for files should be accessible using the "--follow" flag to
git log, eg:

    git log --follow docs/source/adc.rst

It should be possible to pull patches from leaflabs-docs with:

    git pull -s subtree leaflabs-docs master

... at least until the docs in this repository diverge significantly.

1 files changed, 189 insertions, 0 deletions

diff --git a/docs/source/lang/api/board-values.rst b/docs/source/lang/api/board-values.rst
new file mode 100644
index 0000000..d944c8d
--- /dev/null
+++ b/docs/source/lang/api/board-values.rst
@@ -0,0 +1,189 @@
+.. highlight:: cpp
+
+.. _lang-board-values:
+
+Board-Specific Values
+=====================
+
+There are a number of board-specific values: constants or variables
+which are different depending on which LeafLabs board you have.  The
+exact values for each board are given in your :ref:`board's hardware
+documentation <index-boards>`.
+
+This page lists and documents the board-specific values.  You should
+use these when appropriate in your own programs.  This will help make
+it easier to share your code with other people who have different
+boards.  Some example usages are given :ref:`below
+<lang-board-values-examples>`.
+
+.. contents:: Contents
+   :local:
+
+Constants
+---------
+
+- ``CYCLES_PER_MICROSECOND``: Number of CPU cycles per microsecond on
+  your board.
+
+- ``CLOCK_SPEED_MHZ``: Clock speed of your board, in megahertz
+  (MHz). This is the same as ``CYCLES_PER_MICROSECOND``.
+
+- ``CLOCK_SPEED_HZ``: Clock speed of your board, in hertz (Hz).  This
+  is the same as ``CLOCK_SPEED_MHZ`` × 1,000,000.
+
+- ``SYSTICK_RELOAD_VAL``: Value used when reloading the :ref:`systick`
+  timer's counter [#fmillis]_.
+
+.. _lang-board-values-but:
+
+- ``BOARD_BUTTON_PIN``: Pin connected to the built-in button (labeled
+  "BUT" on your board's silkscreen).
+
+.. _lang-board-values-led:
+
+- ``BOARD_LED_PIN``: Pin connected to the built-in LED.
+
+- ``BOARD_NR_GPIO_PINS``: Total number of :ref:`GPIO pins <gpio>` that
+  are broken out to headers.  Some of these might already be connected
+  to external hardware (like the built-in LED and button).  To find
+  out if a pin is in use, see :ref:`boardUsesPin()
+  <lang-boardusespin>` (and also :ref:`boardUsedPins
+  <lang-board-values-used-pins>`).
+
+.. _lang-board-values-nr-pwm-pins:
+
+- ``BOARD_NR_PWM_PINS``: Total *number* of GPIO pins that can be used
+  for :ref:`PWM <pwm>`.  The actual *pins* that can do PWM are in the
+  :ref:`boardPWMPins <lang-board-values-pwm-pins>` array.
+
+.. _lang-board-values-nr-adc-pins:
+
+- ``BOARD_NR_ADC_PINS``: Total number of GPIO pins that can be used
+  for :ref:`analog-to-digital conversion <adc>`.  The actual pins that
+  can do ADC conversion are in the :ref:`boardADCPins
+  <lang-board-values-adc-pins>` array.
+
+.. _lang-board-values-nr-used-pins:
+
+- ``BOARD_NR_USED_PINS``: Total number of GPIO pins that are already
+  connected to some external hardware (like a built-in LED) on the
+  board.  The actual pins that that are already used are in the
+  :ref:`boardUsedPins <lang-board-values-used-pins>` array.  To see if
+  a pin is already in use, use the :ref:`boardUsesPin()
+  <lang-boardusespin>` function.
+
+.. _lang-board-values-usart:
+
+- :ref:`USART <usart>` (serial port) related constants:
+
+    * ``BOARD_USART1_TX_PIN``, ``BOARD_USART2_TX_PIN``, ``BOARD_USART3_TX_PIN``:
+      TX pins for the 3 USARTS.
+
+    * ``BOARD_USART1_RX_PIN``, ``BOARD_USART2_RX_PIN``, ``BOARD_USART3_RX_PIN``:
+      RX pins for the 3 USARTS.
+
+    * ``BOARD_UART4_TX_PIN``, ``BOARD_UART5_TX_PIN``: TX pins for
+      UARTs 4 and 5 (high-density boards like Maple Native only).
+
+    * ``BOARD_UART4_RX_PIN``, ``BOARD_UART5_RX_PIN``: RX pins for
+      UARTs 4 and 5 (high-density boards like Maple Native only).
+
+    * ``BOARD_NR_USARTS``: Number of serial ports on the board.  This
+      number includes UARTs 4 and 5 if they are available.
+
+- :ref:`SPI <spi>` related constants:
+
+    * ``BOARD_SPI1_NSS_PIN``, ``BOARD_SPI1_MOSI_PIN``,
+      ``BOARD_SPI1_MISO_PIN``, ``BOARD_SPI1_SCK_PIN``: SPI1
+      peripheral's NSS, MOSI, MISO, and SCK pins, respectively.
+
+    * ``BOARD_SPI2_NSS_PIN``, ``BOARD_SPI2_MOSI_PIN``,
+      ``BOARD_SPI2_MISO_PIN``, ``BOARD_SPI2_SCK_PIN``: SPI2
+      peripheral's NSS, MOSI, MISO, and SCK pins, respectively.
+
+    * ``BOARD_SPI3_NSS_PIN``, ``BOARD_SPI3_MOSI_PIN``,
+      ``BOARD_SPI3_MISO_PIN``, ``BOARD_SPI3_SCK_PIN``: SPI3
+      peripheral's NSS, MOSI, MISO, and SCK pins, respectively
+      (available on high-density devices like Maple Native and Maple
+      RET6 edition only).
+
+    * ``BOARD_NR_SPI``: Number of SPI peripherals on the board.
+
+.. _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 and Maple RET6
+  Edition, as writing to ``BOARD_NJTRST_PIN`` :ref:`may cause your
+  board to reset <maple-nrst-pb4>`\ !).
+
+.. _lang-board-values-pwm-pins:
+
+.. _lang-board-values-adc-pins:
+
+.. _lang-board-values-used-pins:
+
+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.
+
+- ``boardPWMPins``: Pin numbers of each pin capable of :ref:`PWM
+  <pwm>` output, using :ref:`pwmWrite() <lang-pwmwrite>`.  The total
+  number of these pins is :ref:`BOARD_NR_PWM_PINS
+  <lang-board-values-nr-pwm-pins>`.
+
+- ``boardADCPins``: Pin numbers of each pin capable of :ref:`ADC
+  <adc>` conversion, using :ref:`analogRead() <lang-analogread>`.  The
+  total number of these pins is :ref:`BOARD_NR_ADC_PINS
+  <lang-board-values-nr-adc-pins>`.
+
+- ``boardUsedPins``: Pin numbers of each pin that, by default, is used
+  for some special purpose by the board.  The total number of these
+  pins is :ref:`BOARD_NR_USED_PINS <lang-board-values-nr-used-pins>`.
+  To check if a pin is used for a special purpose, use
+  :ref:`boardUsesPin() <lang-boardusespin>`.
+
+.. _lang-board-values-examples:
+
+Examples
+--------
+
+:ref:`BOARD_LED_PIN <lang-board-values-led>` On the Maple, the
+built-in LED is connected to pin 13.  On the Maple Mini, however, it
+is connected to pin 33.  You can write a "blinky" program that works
+on both boards using :ref:`this example <lang-toggleled-example>`.
+
+:ref:`BOARD_BUTTON_PIN <lang-board-values-but>`: On the Maple, the
+built-in button is connected to pin 38.  On the Maple Mini, however,
+it is connected to pin 32.  :ref:`This example
+<lang-waitforbuttonpress-example>` shows how you can write a program
+that prints a message whenever the button is pressed which will work
+on all LeafLabs boards.
+
+See Also
+--------
+
+- :ref:`lang-boardusespin`
+- :ref:`lang-isbuttonpressed`
+- :ref:`lang-waitforbuttonpress`
+- :ref:`lang-pinmode`
+- :ref:`lang-toggleled`
+- :ref:`lang-analogread`
+- :ref:`lang-pwmwrite`
+- :ref:`lang-enabledebugports`
+- :ref:`lang-disabledebugports`
+
+.. rubric:: Footnotes
+
+.. [#fmillis] In order for :ref:`lang-millis` to work properly, this
+   must be ``CYCLES_PER_MICROSECOND`` × 1,000 - 1.