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.
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 three 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.

 * **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

Always replace :file:`<target>` by the relevant target prefix in 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"

        "AARCH64 ELF", "aarch64-elf-gnatemu"
        "ARM ELF", "arm-eabi-gnatemu"
        "LEON 3 ELF", "leon3-elf-gnatemu"
        "MORELLO ELF", "morello-elf-gnatemu"
        "PowerPC ELF", "powerpc-elf-gnatemu"
        "RISCV32 ELF", "riscv32-elf-gnatemu"
        "RISCV64 ELF", "riscv64-elf-gnatemu"
        "X86_64 ELF", "x86_64-elf-gnatemu"