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, 170 insertions, 0 deletions

diff --git a/docs/source/lang/api/hardwarespi.rst b/docs/source/lang/api/hardwarespi.rst
new file mode 100644
index 0000000..a44a65f
--- /dev/null
+++ b/docs/source/lang/api/hardwarespi.rst
@@ -0,0 +1,170 @@
+.. highlight:: cpp
+
+.. _lang-hardwarespi:
+
+HardwareSPI
+===========
+
+This page describes how to use the built-in SPI ports.  It does not
+describe the SPI protocol itself.  For more information about SPI, see
+the :ref:`SPI reference <spi>`.
+
+.. contents:: Contents
+   :local:
+
+Getting Started
+---------------
+
+In order to get started, you'll first need to define a ``HardwareSPI``
+variable, which you'll use to control the SPI port.  Do this by
+putting the line "``HardwareSPI spi(number);``" with your variables,
+where ``number`` is the SPI port's number.
+
+Here's an example (we'll fill in :ref:`setup() <lang-setup>` and
+:ref:`loop() <lang-loop>` later)::
+
+   // Use SPI port number 1
+   HardwareSPI spi(1);
+
+   void setup() {
+      // Your setup code
+   }
+
+   void loop() {
+      // Do stuff with SPI
+   }
+
+Turning the SPI Port On
+-----------------------
+
+Now it's time to turn your SPI port on.  Do this with the ``begin()``
+function (an example is given below).
+
+.. FIXME [Breathe] Output doesn't include the class; fix & submit pull req
+
+.. doxygenfunction:: HardwareSPI::begin
+
+.. note:: If you are using SPI port 3 (on a board that supports it;
+   not all do); you'll need to call :ref:`lang-disabledebugports`
+   before calling ``begin()``.
+
+The speed at which the SPI port communicates is configured using a
+``SPIFrequency`` value:
+
+.. FIXME [0.1.0] Breathe's enum output is enormous; shrink & submit pull req
+
+.. doxygenenum:: SPIFrequency
+
+.. note:: Due to hardware issues, you can't use the frequency
+   ``SPI_140_625KHz`` with SPI port 1.
+
+The "mode" value determines the clock phase and polarity, like so:
+
+.. doxygenenum:: spi_mode
+
+You'll need to determine the correct values for ``frequency``,
+``bitOrder``, and ``mode`` yourself, by consulting the datasheet for
+the device you're communicating with.  Continuing our example from
+before, we'll add a call to ``begin()`` to our ``setup()``::
+
+   // Use SPI port number 1
+   HardwareSPI spi(1);
+
+   void setup() {
+       // Turn on the SPI port
+       spi.begin(SPI_18MHZ, MSBFIRST, 0);
+   }
+
+   void loop() {
+      // Do stuff with SPI
+   }
+
+If you call ``begin()`` with no arguments (as in "``spi.begin();``"),
+it's the same as if you wrote "``spi.begin(SPI_1_125MHZ, MSBFIRST,
+0);``".
+
+Communicating Over SPI
+----------------------
+
+Now that you've got your SPI port set up, it's time to start
+communicating.  You can send data using ``HardwareSPI::write()``,
+receive data using ``HardwareSPI::read()``, and do both using
+``HardwareSPI::transfer()``.
+
+.. cpp:function:: void HardwareSPI::write(byte data)
+
+   Send a single byte of data.
+
+   **Parameters**:
+
+   - ``data``: Byte to send
+
+.. cpp:function:: byte HardwareSPI::read()
+
+   Get the next available, unread byte.  If there aren't any unread
+   bytes, this function will wait until one is received.
+
+.. cpp:function:: byte HardwareSPI::transfer(byte data)
+
+   Send a byte, then return the next byte received.
+
+   **Parameters:**
+
+   - ``data``: Byte to send
+
+   **Returns:** Next unread byte
+
+Continuing our example from before, let's send a number over SPI and
+print out whatever we get back over :ref:`lang-serialusb`::
+
+   // Use SPI port number 1
+   HardwareSPI spi(1);
+
+   void setup() {
+       // Turn on the SPI port
+       spi.begin(SPI_18MHZ, MSBFIRST, 0);
+   }
+
+   void loop() {
+      // Send 245 over SPI, and wait for a response.
+      spi.write(245);
+      byte response = spi.read();
+      // Print out the response received.
+      SerialUSB.print("response: ");
+      SerialUSB.println(response, DEC);
+   }
+
+HardwareSPI Class Reference
+---------------------------
+
+There are a number of other things you can accomplish with your
+``spi`` object.  A full function listing follows.
+
+.. doxygenclass:: HardwareSPI
+   :members: HardwareSPI, begin, beginSlave, end, read, write, transfer
+
+Deprecated Functions
+--------------------
+
+The following functions are defined for now, but they have been
+deprecated, and will be removed in a future Maple IDE release.  You
+shouldn't use them in new programs, and you should change any of your
+programs which do use them to the up-to-date functions discussed
+above.
+
+.. cpp:function:: uint8 HardwareSPI::send(uint8 *data, uint32 length)
+
+   Writes ``data`` into the port buffer to be transmitted as soon as
+   possible, where ``length`` is the number of bytes to send from
+   ``data``.  Returns the last byte shifted back from slave.
+
+.. cpp:function:: uint8 HardwareSPI::send(uint8 data)
+
+   Writes the single byte ``data`` into the port buffer to be
+   transmitted as soon as possible.  Returns the data byte shifted
+   back from the slave.
+
+.. cpp:function:: uint8 HardwareSPI::recv()
+
+   Reads a byte from the peripheral.  Returns the next byte in the
+   buffer.