x86_64 ELF Topics¶
This appendix describes topics relevant to GNAT for bareboard x86-64 ELF and also presents a tutorial on building, running, and debugging an Ada application in GNATemulator.
Supported Processors and Run-Time Libraries¶
GNAT for bareboard x86-64 ELF targets the Intel 64 architecture (also known as AMD64 or x86-64).
Out of the box GNAT provides run-time support for the following Intel processor families:
Core and Xeon families: processors based on the Sandy Bridge microarchitecture and newer.
Atom families: processors based on the Goldmont microarchitecture and newer.
For these processors the following generic run-times are provided:
All run-time libraries include the necessary low-level hardware startup and initialization functionality required to run applications on systems containing the supported processor families. The run-times only support running on a single core.
Required CPU Features¶
While the Light run-time has the ability to run on any x86-64 processor, the Light-Tasking and Embedded run-times require the following CPU features that are only present in the supported processor families:
Invariant Time-Stamp Counter
The run-time will check for these features on boot and will raise a run-time error if the processor does not support them.
Running a x86_64-elf Application¶
The x86_64-elf run-times are designed to be booted from a variety of different bootloaders via bootloader-specific linker scripts. Shipped with GNAT Pro is support for:
Multiboot 1 and Multiboot 2 complaint bootloaders (like GRUB)
LynxSecure (as a LynxSecure Application)
By default, applications are built for GNATemulator. To build your application
for one of the other supported bootloaders, set the
LOADER project variable
LOADER variable can be
specified as a switch to GPRBuild:
gprbuild -P proj.gpr -XLOADER=MULTIBOOT
or in GNAT Studio by adding the following to your project file:
type LOADER_Type is ("MULTIBOOT"); LOADER : LOADER_Type := external ("LOADER", "MULTIBOOT");
By default, applications are built to run in GNATemulator. To run your program
you can either press the
Run with Emulator toolbar button in GNAT Studio
or run directly from the command line with:
MULTIBOOT2 loaders allow the resulting ELF binary to
be booted directy using a multiboot complaint bootloader like GRUB.
LSA loader produces an application that can be loaded as a LynxSecure
Application (LSA). To add the application to a LynxSecure SRP, you first need
to convert the ELF binary to a raw binary image:
x86_64-elf-objcopy -O binary <program> <program>.bin
Once converted, the application can be included in an SRP with the following switch:
The run-times are configured to use serial port COM1 with the system default serial configuration.
The Ravenscar run-times use the invariant Time-Stamp Counter (TSC) and Local
APIC Timer as their clock sources and will attempt to determine the frequencies
of these clock sources on boot, based on the information provided to it by the
processor. On some processors this information may be unavailable, and the
run-time will raise a program error indicating this problem. If this occurs,
the TCS and Local APIC Timer frequency will need to be manually set in
System.BB.Parameters. You may also need to manually set this frequency
if the run-time determines the wrong TCS or Local APIC Timer frequencies.
x86-64 uses a split interrupt controller design. Each CPU has its own Local Advanced Programmable Interrupt Controller (APIC) that can receive external interrupts from PCI devices via the Message Signaled Interrupts (MSI) feature or from I/O APICs.
The Ravenscar run-times only support attaching protected procedure handlers to Local APIC interrupt vectors via the Attach_Handler aspect. Interrupt vectors 33 to 254 are available for user applications, with Interrupt 32 reserved for the Spurious Interrupt Vector and Interrupt 255 reserved for the APIC Timer as used by the run-time. See Ada.Interrupts.Names for the list of vectors.
Note that interrupt priorities are handled differently by the Intel Local APIC compared to interrupt controllers used by other processors. The Local APIC encodes the interrupt priority of a vector in the top 4 bits of the 8-bit vector number. Consequently, when attaching a protected procedure to an interrupt vector you need to ensure that the Interrupt Priority of the protected object corresponds to the priority class of the interrupt vector. Please refer to Ada.Interrupts.Names for a mapping of vector numbers to Interrupt Priorities, as the run-time will enforce these mappings.
To attach a handler to an I/O APIC IRQ, route the IRQ to a Local APIC Vector using the Route procedure provided in Interfaces.X86_64.IO_APIC and attach the protected handler to the Vector. Then unmask the IRQ using the Mask procedure. For example, in the following code we connect a protected handler called Signal to IRQ4 by routing it to Local APIC Vector 33 and attaching the handler to that vector:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
with Ada.Interrupts.Names; use Ada.Interrupts.Names; with Interfaces.X86_64.IOAPIC; use Interfaces.X86_64.IOAPIC; package My_Pack is protected Handler_Object with Interrupt_Priority => Vector_32_47_Interrupt_Priority is procedure Initialize; procedure Signal with Attach_Handler => Vector_33; end Handler_Object; end My_Pack; package body My_Pack is protected body Handler_Object is procedure Initialize is begin Route (Interrupt => IRQ4, To_Vector => Vector_33); Unmask (IRQ4); end Enable_External_Interrupt; procedure Signal is begin Ada.Text_IO.Put_Line ("Interrupt handled"); end Signal; end Handler_Object; end My_Pack;
The GNAT for bareboard x86-64 run-times are designed to be loaded by a bootloader into RAM. By default the run-times are configured to use 128MB. If your system has more or less memory, modify memory-map.ld to suite your requirements or provide your own linker script by setting the environment variable LOADER to ‘USER’ and specifying the linker script via the ‘-T’ linker switch. The run-times will not automatically detect the amount of RAM in the system.
Developing with GNAT for bareboard 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. These 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 Introduction to GNAT for Cross Platforms. For the x86-64 the target x86_64-elf needs to be specified.
For example, the following project file fragment shows both the target and the run-time library specified via their respective attributes:
project Demo is ... for Runtime ("Ada") use "light-x86_64"; for Target use "x86_64-elf"; ... end Demo;
The second difference is how programs are run and debugged. This is dependent on your setup and the tools you use. In many cases, GNAT Studio can be used to debug your program. See Debugging for details.
Getting Started with GNATemulator¶
This guide describes how to set up, build, run, and debug an Ada application on GNATemulator. Setup for both Windows and Linux hosts is covered. While this section focuses on GNATemulator, most of the steps contained within this section are independent of the application and the target hardware itself.
To begin this setup, it is assumed that GNAT for bareboard x86-64 has been installed and that the install bin directory is in the PATH environment variable.
Creating a new Project¶
Launch GNAT Studio:
If this is your first time running GNAT Studio, note that GNAT Studio will create a configuration directory and will alert you via a pop-up dialog box. Press ‘OK’ to close that box and continue. A ‘Tip of the Day’ dialog will appear. Press Close to dismiss it.
When on the Welcome page, click on
Create new project and select
Simple Ada project, and then click on
Next. Change Location and
Settings appropriately and press
The project view is now displayed. Next, open the project properties by
right-clicking on the project name in Project tab, and selecting
Project->Properties. With the project properties displayed open the
Toolchains tab, and make sure that the x86_64-elf toolchain is selected
and the Ada run-time is light-x86_64. Then click on
You can now add your source code.
Within GNAT Studio, build the project using either the
Build Main button on
the toolbar, or the
Build/Project->Build All menu entry. In
the latter case, if a pop-up window appears, press the
button in order to build with the default settings.
As GNAT Studio builds the project, it will display the
Messages view at the bottom
of the GNAT Studio window to show information about the build. On a successful build,
Memory Usage view will graphically display the memory usage of the
program, unless the preference is disabled. (See the preference
Build Targets/Project/Build Main page, among others, containing the
memory usage check-box.)
Running the Program¶
Within GNAT Studio, run your program on the emulator using the
Run with Emulator
toolbar button or the Build/Emulator->Run with Emulator menu entry.
As the program executes, it will display its output, if any, in the x86_64-elf-gnatemu view.
Debugging the Program¶
In GNAT Studio, click on the
Debug with Emulator button on the toolbar.
This will start a GNAT Studio debug session and launch the necessary tools
required to debug the program on the emulator from GNAT Studio. The emulator
will be automatically launched. Debugging a program on the emulator through
GNAT Studio is similar to debugging a native program:
The program can continue to the next breakpoint by pressing the
Continuebutton on the toolbar or by using the
The program can be stepped through statements using the corresponding menu items in
Debugmenu and buttons on the toolbar.
The program can be interrupted by pressing
<ctrl>-\, or through the
Breakpoints can be set via the
Breakpointsview, by clicking on the line numbers in the source editor while the program is interrupted, or by right-clicking on the desired line and selecting
Set breakpoint on line ...from the
Variables can be queried from the
Variablesview or by hovering the mouse over a variable with the program interrupted.
GNAT Studio also provides a
Debugger Console view that allows shell access
to the underlying GDB client that is debugging the program. Arbitrary GDB
commands, including the commands corresponding to the above, can be entered
into the console if desired.
The debugging session can be exited via the
Debug/Terminate menu or
by issuing the
quit command in the