.. _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)