diff options
Diffstat (limited to 'docs/source/arm-gcc.rst')
-rw-r--r-- | docs/source/arm-gcc.rst | 107 |
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) |