.. index:: AVR-ELF Topics .. _AVR-ELF_Topics: ============== AVR-ELF Topics ============== This Appendix describes topics relevant to GNAT Pro for AVR-ELF and also presents a tutorial on building, running, and debugging a C application on an embedded AVR board. .. _AVR-ELF_Introduction: Introduction to GNAT Pro for AVR-ELF ==================================== The AVR-ELF toolset targets AVR 8-Bit RISC microcontrollers from Atmel. AVR microcontrollers have limited resources: 32 8-bit wide registers, separate instructions and data memory, at most 256KB of flash for the instructions, and at most 64KB of internal SRAM for the data. There is a large number of microcontrollers, and although they have the same instructions set core, they vary in capabilities. Some low-end models can be programmed only in assembly, while at the higher end one finds dedicated instructions to handle a larger amount of memory. GNAT Pro has been tested only with the atmega128x, with less support for the other microcontrollers. Compiler and Linker Flags for AVR-ELF ===================================== The compiler must know which microcontroller is targeted, because code generation is affected. Use option ``-mmcu=ARCH`` where ``ARCH`` is the AVR architecture defined as follow: * For ``atmega2560`` and ``atmega2561`` use ``-mmcu=avr6``. * For enhanced cores with 128KB of flash ``atmega128x`` and ``at90usb128x`` use ``-mmcu=avr51``. * For enhanced cores whose flash size is between 8KB and 64KB use ``-mmcu=avr5``. * For enhanced cores with less than 8KB of flash use ``-mmcu=avr4``. Do not try to link object files compiled for different targets, since the code generated is not compatible. The program should be compiled and linked with option ``-nostdlib`` to prevent linking with standard libraries (such as the C library) which are not provided by GNAT Pro. However, option ``-lgcc`` should be passed to the linker to link with the compiler support library. .. _AVR-ELF_Getting_Started: Getting Started =============== Developing with GNAT for bareboard AVR is similar to native GNAT development, with two important differences. First, when building for a bareboard target you need to specify both the target processor and the run-time library. This can be defined in a project file (either directly or via the project properties dialog in GNAT Studio) or on the command line. For details on how to specify the target and run-time library for your project, see :ref:`introduction`. For all supported AVR boards, the target 'avr-elf' needs to be specified. For example, the following project file fragment shows the target specified via their respective attributes. In this example, an AVR target is specified: .. code-block:: gpr project Demo is ... for Target use "avr-elf"; ... end Demo; The second difference is how programs are run and debugged. This is dependent on your setup and the tools you use. For example, a debug probe can be used to download programs to an AVR microcontroller's embedded flash or RAM. In this instance refer to the documentation accompanying the probe. In many cases, GNAT Studio can be used to debug your program if your debug probe provides a GDB server. See :ref:`Debugging` for details. Getting started with GNATemu ---------------------------- This guide describes how to setup, build, run, and debug a C application on GNATemu. The example used by this guide, :file:`atmega` can be found in the directory: :file:`/share/examples/atmega>` This simple example displays the "Hello World!!!" string. If you have installed GNAT in a shared location you may first need to copy the example to a directory that you have write access to (e.g. in your home directory). The example has a typical project layout, capturing the sources for the project within the :file:`src` directory while the object and other generated files are stored in the :file:`obj` directory. :file:`example.gpr` is the GPR project file for the example that captures the project settings, including the target used by the project. .. _AVR-ELF_Example_Building: Building -------- The project can easily be built with the following shell command from the :file:`/share/examples/atmega>` directory: :: $ [BUILD=Debug] gprbuild -P example.gpr Setting the ``BUILD`` environment variable to ``Debug`` will build the program with debug options. Set this variable if you intend to debug the program. .. _AVR-ELF_Running_The_Example: Running the Example ------------------- The program can be run with the following shell command from the :file:`/share/examples/atmega>` directory: :: $ avr-gnatemu [-g] obj/main The ``-g`` option opens the default debug port and freezes the emulation on startup. This option should only be used if you intend to connect a debugger to the emulator as described in :ref:`AVR-ELF_Debugging_The_Example`. .. _AVR-ELF_Debugging_The_Example: Debugging the Example --------------------- After the emulator has been launched with the ``-g`` option, it is possible to launch the debugger with the following shell command from the :file:`/share/examples/atmega>` directory: :: $ avr-gdb obj/main (gdb) target remote localhost:1234 ... (gdb) break main (gdb) continue ... (gdb) detach