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)