XtratuM Topics

This appendix describes topics that are specific to the GNAT for XtratuM cross configurations on ARM and LEON.


The Ravenscar run-time library can be executed on top of the XtratuM hypervisor for LEON or ARM; it has been para-virtualized to use the virtual machine interface provided by XtratuM.

The library is distributed in the form of a source package containing a project-based run-time library (see section Customized Run-Time Libraries for detailed information about this topic).

Executing on top of XtratuM

This section describes how to build the XtratuM run-time library and how to use it to execute an Ada program on top of XtratuM. It uses leon3-elf as an example; for other targets, replace leon3-elf with the proper target prefix (e.g. arm-eabi).

Before building or using this library, the XTRATUM_PATH must be properly set pointing to the directory containing the XtratuM kernel and the associated developer utilities (the directory xm).

The run-time library can be built using the following command:

$ tar xzf ravenscar-full-xtratum.tar.gz
$ gprbuild --target=leon3-elf -P ravenscar-full-xtratum/runtime_build.gpr

This library can only be used through a project file with gprbuild. Any project file can be used, even a simple one as the following. This one sets the main source file name to ada_main.adb, sets the name of the generated binary ELF file to partition1, and sets the text section at address 0x40080000 (it must be the same as the one declared in the XtratuM XM_CF file):

project Prj is
   for Main use ("ada_main.adb");

   package Builder is
      for Executable ("ada_main.adb") use "partition1";
   end Builder;

   package Linker is
      for Default_Switches ("ada") use ("-Ttext=0x40080000");
   end Linker;
end Prj;

Then, the Ada partition can be built doing:

$ gprbuild --target=leon3-elf --RTS=<RTS> -P prj.gpr

where <RTS> is the root directory of the run-time library being used.

The need to specify the path to the run-time library can be avoided by installing the library in a place known by the compiler. If the ravenscar-full-xtratum directory is placed as a subdirectory of <gnat-root>/lib/gnat/leon3-elf then the previous gprbuild command can be transformed into the following:

$ gprbuild --target=leon3-elf --RTS=leon3-elf/ravenscar-full-xtratum -P prj.gpr

The generated partition1 ELF file can then be converted to XEF format, packed into a container and integrated with the resident software using the following Makefile (derived from the XtratuM examples).

These considerations also apply if the Runtime and Target attributes are used instead of the command-line switches. The attributes are preferred, and are discussed in Specifying the Run-Time Library and Target.

It can also be convenient to avoid specifying the address of the text section in the project file, and pass it from the command line using the XtratuM xpathstart tool; for that, the option to be passed to the linker is: -largs -Ttext=$(shell $(XPATHSTART) 0 $(XMLCF)). The same applies to the data section, the linker command being: -largs -Tdata=$(shell $(XPATHSTART) 1 $(XMLCF)). The following is a possible Makefile integrating an Ada partition, where the project file prj.gpr only needs to specify the main Ada unit:

# XAL_PATH: path to the XTRATUM directory

# XMLCF: path to the XML configuration file

# PARTITIONS: partition files (xef format) composing the example

all: container.bin resident_sw
include $(XAL_PATH)/common/rules.mk

PACK_ARGS=-h $(XMCORE):xm_cf.xef.xmc \
        -p 0:partition1.xef

partition1: $(ADA_FILES)
        gprbuild --target=leon3-elf --RTS=leon3-elf/ravenscar-full-xtratum \
        -P prj.gpr -o $@ -largs -Ttext=$(shell $(XPATHSTART) 0 $(XMLCF)) \
        -Tdata=$(shell $(XPATHSTART) 1 $(XMLCF))

container.bin: $(PARTITIONS) xm_cf.xef.xmc
        $(XMPACK) check xm_cf.xef.xmc $(PACK_ARGS)
        $(XMPACK) build $(PACK_ARGS) $@
        @exec echo -en "> Done [container]\n"