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

diff --git a/docs/source/arm-gcc.rst b/docs/source/arm-gcc.rst
new file mode 100644
index 0000000..30667a2
--- /dev/null
+++ b/docs/source/arm-gcc.rst
@@ -0,0 +1,107 @@
+
+.. _arm-gcc:
+
+GCC and libc
+============
+
+This document provides notes on using ``arm-none-eabi-gcc``, the
+`CodeSourcery <http://www.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/>`_.
+
+.. contents:: Contents
+   :local:
+
+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`` 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 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.
+
+.. _arm-gcc-compiler-flags:
+
+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 the
+:ref:`Unix toolchain <unix-toolchain>`.  The information in this
+section is subject to change between :ref:`libmaple <libmaple>`
+releases.
+
+.. highlight:: sh
+
+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
+
+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
+
+The following flags are among those passed to the assembler::
+
+    -mcpu=cortex-m3 -march=armv7-m -mthumb
+
+.. highlight:: cpp
+
+.. _arm-gcc-libc:
+
+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.
+
+Be advised, however, that a variety of syscalls may only be partially
+implemented, if at all.  See the :ref:`libmaple` file syscalls.c and
+the newlib documentation for more details.
+
+.. _arm-gcc-avr-gcc:
+
+Switching from AVR-GCC
+----------------------
+
+This section, which is expected to grow over time, describes
+techniques for porting code which uses AVR-GCC features (AVR-GCC is
+the compiler used by many Atmel AVR-based microcontroller boards,
+including Arduino) for use on the Maple.
+
+.. _arm-gcc-attribute-flash:
+
+- Replacing ``PROGMEM``: If you need to store a lot of constant data,
+  you can store variables in Flash (instead of RAM) by using the
+  libmaple macro ``__FLASH__``.  Here's an example::
+
+      uint32 array[] __FLASH__ = {0, 1, 2};
+
+  This will help you save RAM when you need to store large amounts of
+  data, like look-up tables.
+
+  You can only store values which are compile-time constants (like
+  numbers and strings, and arrays of numbers and strings) in this way.
+  Also, if you try to change a variable stored in Flash, your program
+  will crash.
+
+  If you need to port over AVR/Arduino code that uses pgmspace.h,
+  these declarations may help you::
+
+      typedef const unsigned char prog_uchar;
+      #define pgm_read_byte_near(x) (*(prog_uchar*)x)
+      #define pgm_read_byte(x) (*(prog_uchar*)x)