Introduction
============

About GNATemulator
------------------

Simulators are useful tools in many respects. Installation, setup and
deployment to a development team will prove to be easier and quicker than with
a real target. Simulator usage on a native platform will also bring more
flexibility in the development of the application.

GNATemulator is particularly suited for functional testing and unit
testing. The product comes with a complete simulation environment and related
BSP for non bareboard systems such as VxWorks 653. It allows for efficient 
target code execution. It simulates a simple board and does not aim at 
complete board simulation. This should be mostly transparent to the application 
developer as the differences between the real target and the simulator should
be handled and hidden by the platform provider.

Product Content
---------------

The product contains four components:

 * **The Simulator**: This is the heart of the product. The main tool is
   called :file:`gnatemu` and is prefixed by the relevant target name.
   Under the hood it relies on the **QEMU** processor and board simulator.
   **GNATemulator** efficiently runs the executable: the
   target code is translated on the fly, one basic block at a time, to
   the host processor. The translated code is then kept in a cache so that
   no new translation is required when the execution passes through a basic
   block that has been executed.
   An important point to keep in mind is that **GNATemulator** is translating
   and executing instructions as fast as possible and thus won't be cycle
   accurate. The clock used by **GNATemulator** is the host system clock.
   Timing events are thus dependent on that clock and will not reflect the
   timing characteristics of a real target board.

 * **The BSP**: On non-bareboard systems, a BSP is provided when necessary.
   This is the case for example on **VxWorks 653**. On that
   target we provide a **BSP** called ``qemu`` that should be installed in
   the **VxWorks 653** installation.
   The BSP simulates a board with one UART (serial link), one ethernet
   controller, a timer, ROM and 128MB of RAM.

 * **GNAT Bus**: A native framework to emulate devices
   (see :ref:`extending-gnatemulator` chapter).

 * **The examples**: For each supported platform there are examples that
   can be used as a reference for further development with **GNATemulator**

Note on the Documentation
-------------------------

As mentioned in the previous section the main tool name is::

        <target>-gnatemu

Along this documentation, in the sections that are not target specific we will
use :file:`gnatemu` for the tool name, skipping the target prefix. In that
cases always replace :file:`gnatemu` by :file:`<target>-gnatemu` where
:file:`<target>` is the relevant target prefix for your context.

As a reminder here is the list of target supported by **GNATemulator** along
with the expected tool name:

.. csv-table::
        :header: "Platform", "Tool name"

        "PowerPC e500v2 VxWorks 6.x", "e500v2-wrs-vxworks-gnatemu" 
        "PowerPC VxWorks 6.x", "powerpc-wrs-vxworks-gnatemu"
        "PowerPC VxWorks 653", "powerpc-wrs-vxworksae-gnatemu"
        "PowerPC ELF", "powerpc-elf-gnatemu"
        "PowerPC 55xx and e500v2 ELF", "powerpc-eabispe-gnatemu"
        "LEON 2 ELF", "leon-elf-gnatemu"
        "LEON 3 ELF", "leon3-elf-gnatemu"
        "ARM ELF", "arm-eabi-gnatemu"

