Ada Bare Bones

The aim of this tutorial is to produce a small Multiboot kernel written in the Ada programming language.

Preface

One of the first things people ask on the Ada IRC channel on Freenode is "Can Ada be used for OS development?" to which the answer is a resounding yes.

Prerequisites

The following section details the prerequisite software necessary for successfully building the kernel.

Cross-Compiler

Main article: GNAT Cross-Compiler

This tutorial requires the use of a cross-compiler with Ada support targeting the i686-elf architecture. Theoretically, any Ada compiler capable of producing bare-metal ELF binaries for this architecture is suitable. The recommended compiler is GNAT, which is part of the GNU Compiler Collection maintained by the Free Software Foundation. Historically it was difficult to create cross-compiler builds for GNAT, but recent versions of GCC have made this much simpler. For a tutorial on how to set up a GNAT cross-compiler, refer to this article.

GPRbuild

This tutorial will require the use of the GPRBuild utility to build GNAT project files. GPRbuild is a generic build tool designed for the construction of multi-language systems. It is included with AdaCore's distribution of their proprietary GNAT compiler: [1] or can be built from source files obtained from AdaCore's github profile. Older versions of GNAT distributed by the Free Software Foundation were able to build GNAT project files using the gnatmake utility, however newer versions do not support all the required features.

The cross-compiler mentioned above will need to be properly integrated with GPRbuild and its associated tools. This can be accomplished by following the guide detailed here.

Ada run-time library

Main article: Ada Runtime Library

The Ada run-time library is responsible for the implementation of the standard library as defined in the Ada Language Reference Manual. Not all features outlined in the reference manual need to be implemented for every platform. Since the kernel will be running in a freestanding environment without the support of an underlying operating system, it will be built with what is known as a a zero-footprint run-time system (commonly abbreviated as 'ZFP'). A zero-footprint RTS will typically provide only the bare-minimum functionality for the target architecture.

The following steps will detail how to create an initial zero-footprint runtime library suitable for building the kernel.

The first step is to set up the directory structure to hold the runtime library. GNAT expects the runtime library to conform to the a set directory structure. It requires the presence of two directories: adalib and adainclude. adainclude contains the runtime package specifications and source files, which are used analogously to include files in C. adalib contains the compiled binary artifacts of the runtime library.

The following code demonstrates setting up a directory structure for the RTS:

mkdir -p bare_bones/src/pc
cd bare_bones
mkdir -p rts/boards/i386/adalib
mkdir -p rts/boards/i386/adainclude
mkdir -p rts/src
mkdir -p obj

The best way to begin creating a new run-time library is to base it upon the existing source files obtained from the system GNAT installation, modifying them where necessary.

The following code demonstrates copying the required files from the host system's GNAT installation's run-time library into rts/src and then creating symbolic links to rts/boards/${arch}/adainclude. Where ${arch} is i386, armv6, etc. The source location will need to be modified to reflect the location of the system compiler.

system_compiler_dir="/usr/lib/gcc/x86_64-linux-gnu/8"
rts_dir="${PWD}/rts"

for f in "ada.ads" "a-unccon.ads" "a-uncdea.ads" "gnat.ads" "g-souinf.ads" \
"interfac.ads" "s-atacco.adb" "s-atacco.ads" "s-maccod.ads" "s-stoele.adb" \
"s-stoele.ads"
do
	cp "${system_compiler_dir}/adainclude/$f" "${rts_dir}/src/"
	ln -s "${rts_dir}/src/$f" "${rts_dir}/rts/boards/i386/adainclude/$f"
done

Files

gnat.adc

During compilation the GNAT compiler will search for a file named gnat.adc within the current working directory. This file is expected to contain one or more configuration pragmas that will be applied to the current compilation. These pragma directives instruct the compiler what features of the runtime should be restricted. This is of particular importance to kernel development since many of Ada's features are not supported by a freestanding, bare-metal environment.

These pragma directives can alternatively be placed at the start of the runtime library's system.ads file (see below), however convention dictates using the gnat.adc file for this purpose.

Additionally, it is possible to apply additional global configuration files by appending the following line to the Builder package in a GNAT project file:

   package Builder is
      --  ...
      for Global_Configuration_Pragmas use "kernel.adc";
   end Builder;

It is also possible to instruct the compiler to apply additional files containing configuration pragmas to the current compilation using the switch -gnatec=path on the command line. These configuration pragmas are applied in addition to those found in gnat.adc, if it is present. More information on configuration files can be found in the GNAT documentation: [2]

The GNAT Reference Manual and the Ada Reference Manual provide information on the various configuration pragmas. See below for a list of restriction pragmas useful for a bare bones kernel and runtime:

pragma Discard_Names;
pragma Restrictions (No_Enumeration_Maps);
pragma Normalize_Scalars;
pragma Restrictions (No_Exception_Propagation);
pragma Restrictions (No_Finalization);
pragma Restrictions (No_Tasking);
pragma Restrictions (No_Protected_Types);
pragma Restrictions (No_Delay);
pragma Restrictions (No_Recursion);
pragma Restrictions (No_Allocators);
pragma Restrictions (No_Dispatch);
pragma Restrictions (No_Implicit_Dynamic_Code);
pragma Restrictions (No_Secondary_Stack);

Note: Do not use pragma No_Run_Time. It is obsolete.

Below is an explanation of these configuration pragmas:

Restriction	Purpose
Discard_Names	The Ada compiler automatically generates strings containing the names of enumerated data types, among others. These strings can be used in I/O. type Fruit is (Orange, Banana, Apple); -- Ada defines the following strings, "Orange", "Banana" and "Apple" in an array. -- These strings can be accessed using the 'Image attribute, as in Put (Fruit'Image (Orange)); -- Prints "Orange" to the console. This directive instructs the compiler not to generate these strings.
Normalize_Scalars	Forces all scalars to be initialised. Refer to GNAT RM:Normalize_Scalars for more information.
No_Exception_Propagation	This directive forces the compiler to disallow any attempt to raise an exception over a subprogram boundary. Refer to GNAT RM:No_Exception_Propagation for more information. Note: The GNAT High Integrity Edition documentation states the following: Exception declarations and raise statements are still permitted under this restriction. A raise statement is compiled into a call of __gnat_last_chance_handler. All exceptions that are not handled with an explicit exception handler within its subprogram will be caught with the Last_Chance_Handler subprogram. This will cause a warning to be issued at compile time.
No_Exception_Registration	Ensures no stream operations are performed on types declared in Ada.Exceptions. See GNAT RM:No_Exception_Registration for more information.
No_Finalization	Restricts the use of controlled types. Refer to GNAT RM:No_Finalization for more information.
No_Tasking	This directive restricts all features related to tasking, including the use of protected objects. Refer to GNAT RM:No_Tasking for more information.
No_Protected_Types	This reinforces the above restriction. Refer to GNAT RM:No_Protected_Types for more information.
No_Delay	Restricts the use of delay statements or the calendar package. Refer to GNAT RM:No_Delay for more information.
No_Recursion	Restricts the use of recursion. Refer to GNAT RM:No_Recursion for more information.
No_Allocators	Restricts the use of dynamic memory. This is essential for a bare-metal application, since there is no underlying facility for allocation of dynamic memory. Refer to GNAT RM:No_Allocators for more information.
No_Dispatch	Disallows calling a subprogram using Ada's object-orientated mechanism. Refer to GNAT RM:No_Dispatch for more information.
No_Implicit_Dynamic_Code	Disallows nested subprograms or any other features that generate trampolines on the stack. Refer to GNAT RM:No_Implicit_Dynamic_Code for more information.
No_Secondary_Stack	Ada uses a secondary stack to return unconstrained types, such as arbitrary length strings or variant records. This directive instructs the compiler that there is no secondary stack present, and to restrict the use of code that requires one. Refer to GNAT RM:No_Secondary_Stack for more information.

Passing the -r flag to the binder instructs it to emit a list of further restrictions that are possible to apply to the project.

   package Binder is
      for Default_Switches ("Ada") use ("-r");
   end Binder;

system.ads

Every Ada program must have access to the System package, this essentially tells the compiler what kind of hardware we are building for, therefore there will be 1 system.ads file per architecture your kernel supports.

Copy a system.ads from GCC that matches the target you are working with, in our case this is gcc-<version>/gcc/ada/system-linux-x86.ads, name it system.ads and place it into rts/boards/i386/adainclude/ we need to edit this a bit.

We don't need to change anything from the top as all the integer sizes should be correct. Go to the private part of the spec and change the following values:

1. Command_Line_Args => False
2. Configurable_Run_Time => True
3. Exit_Status_Supported => False
4. Stack_Check_Probes => False
5. Suppress_Standard_Library => True
6. ZCX_By_Default => False
7. GCC_ZCX_Support => False

For more information on these options, see gcc-<version>/gcc/ada/targparm.ads.

Also, add the following line in the private part of the package:

private

   Run_Time_Name : constant String := "Bare Bones Run Time";

According to targparm.ads, it must be the first thing after the private keyword. It should also show up in error messages in parentheses, but I've not managed to get it to show up thus far. This is useful as it should show you which RTS you are currently using, just in case you configure your build incorrectly.

Last chance handler

The Ada runtime requires the presence of a Last_Chance_Handler subprogram. This subprogram is used as a handler for any exceptions that are not explicitly handled within their subprogram. These calls to the Last_Chance_Handler procedure in the case of unhandled exceptions will be automatically generated by the compiler.

In order to facilitate this the last chance handler procedure must be defined somewhere within the program. Typically this is defined within the runtime. The last chance handler procedure may have any name, however the compiler will search for a procedure with external linkage with the name __gnat_last_chance_handler.

Create the following files in the rts/boards/${arch}/adainclude:

last_chance_handler.ads

with System;

procedure Last_Chance_Handler
  (Source_Location : System.Address; Line : Integer);
pragma Export (C, Last_Chance_Handler, "__gnat_last_chance_handler");

last_chance_handler.adb

procedure Last_Chance_Handler
  (Source_Location : System.Address; Line : Integer) is
   pragma Unreferenced (Source_Location, Line);
begin
   --  TODO: Add in board-specific code to dump exception information to serial/screen.
   loop
      null;
   end loop;
end Last_Chance_Handler;

The contents of the Last_Chance_Handler procedure will need to be tailored to the specific platform of the kernel. Typically this procedure will dump information regarding the exception to output media such as a serial port.

Compiling the runtime

Create a file called gnat.gpr in the root directory with the following contents:

library project gnat is
   type Arch_Name is ("i386", "arm");
   type Board_Name is ("pc", "rpi");

   Arch  : Arch_Name  := "i386";
   Board : Board_Name := external ("Board");

   case Board is
      when "pc" =>
         Arch := "i386";
      when "rpi" =>
         Arch  := "arm";
   end case;

   for Source_Dirs use ("rts/boards/" & Arch & "/adainclude");
   for Object_Dir use "obj"; --"rts/boards/" & Arch & "/adalib";

   package Builder is
      Basic_Switches := ("-gnat2005", "-g", "-x", "-a", "-gnatg",
			 "-gnatec=../gnat.adc");

      case Board is
         when "pc" =>
            for Default_Switches ("Ada") use Basic_Switches &
               ("-m32", "-march=i386");
         when "rpi" =>
            for Default_Switches ("Ada") use Basic_Switches &
               ("-march=armv6zk", "-mfpu=vfp", "-mfloat-abi=hard", "-marm",
                "-mcpu=arm1176jzf-s", "-mtune=arm1176jzf-s");
      end case;
   end Builder;

   package Compiler is
      for Default_Switches ("Ada") use ("-O2", "-ffunction-sections", "-fdata-sections");
   end Compiler;

   for Library_Kind use "static";
   for Library_Name use "gnat-4.6";
   for Library_Dir use "rts/boards/" & Arch & "/adalib";
end gnat;

Now compile with the following command:

gprbuild -XBoard=pc -Pgnat.gpr

Inside rts/boards/i386/adainclude/ the RTS sources should be symbolically linked along with the custom last_chance_hander and system files. Inside rts/boards/i386/adalib/ there should be the libgnat-4.6.a file as well as *.ali matching the source files, which are required by GNAT.

Note: Please note that the above lib might need it's name changed as some OSes might have built libgnat with a version number different to the one used here. The system libnat version may be libgnat-4.4.a and GNAT will expect to find that, so change the name in the GPR file accordingly.

startup.s

This is the main system bootstrapping code. This version is PC specific, so place this in the src/pc directory.

Note: This source file is written using GAS syntax.

.global startup                         # Make the startup entry point symbol visible to the linker

# Set up the Multiboot header (see GRUB docs for details)
.set ALIGN,    1<<0                     # Align loaded modules on page boundaries
.set MEMINFO,  1<<1                     # Provide memory map
.set FLAGS,    ALIGN | MEMINFO          # This is the Multiboot 'flag' field
.set MAGIC,    0x1BADB002               # 'magic number' lets your bootloader find the header
.set CHECKSUM, -(MAGIC + FLAGS)         # Checksum required

header:                                 # Must be in the first 8kb of the kernel file
.align 4, 0x90                          # Pad the location counter (in the current subsection) to a 4-byte
                                        # storage boundary. The way alignment is specified can vary with
                                        # host system architecture.
.long MAGIC
.long FLAGS
.long CHECKSUM

# Reserve initial kernel stack space
.set STACKSIZE, 0x4000                  # 0x4000 being 16k.
.lcomm stack, STACKSIZE                 # Reserve 16k stack on a32-bit boundary
.comm  mbd, 4                           # Declare common symbol mbd, allocate it 4-bytes of
                                        # uninitialized memory.
.comm  magic, 4                         # Declare common symbol magic, allocate it 4-bytes of
                                        # uninitialized memory.

startup:
    movl  $(stack + STACKSIZE), %esp    # Set up the stack

# The following saves the contents of the registers as they will likely be
# overwritten because main is not our actual entry point, Bare_Bones is. We
# will use these 2 symbols inside Bare_Bones.

    movl  %eax, magic                   # EAX indicates to the OS that it was loaded by a Multiboot-compliant boot
                                        # loader
    movl  %ebx, mbd                     # EBX must contain the physical address of the Multiboot information
                                        # structure

    call  main                          # Call main (created by gnatbind)

    cli                                 # Disable interrupts. then intentionally hang the system.
                                        # CLI only affects the interrupt flag for the processor on which it is
                                        # executed.

hang:
    hlt                                 # Because the HLT instruction halts until an interrupt occurs, the
                                        # combination of a CLI followed by a HLT is used to intentionally hang
                                        # the computer if the kernel returns.
                                        # HLT is in a loop just in case a single HLT instruction fails to execute
                                        # for some reason, (such as in the case of an NMI).
    jmp   hang

multiboot.ads

I won't show the source to this package as I have made it more Ada-like and it's quite large, so I will link to the current versions, multiboot.ads and multiboot.adb.

Console

Disclaimer: I wrote this package a long time ago and have reformatted it using my current Ada programming style. I have not gone too far into the code, so it may not be the best implementation of an console.

The following 2 files give you access to the VGA console at 80x25 characters. As they are PC specific, they go into the src/pc directory.

console.ads

with System;

package Console is
   pragma Preelaborate (Console);

   type Background_Colour is
     (Black,
      Blue,
      Green,
      Cyan,
      Red,
      Magenta,
      Brown,
      Light_Grey);

   for Background_Colour use
     (Black      => 16#0#,
      Blue       => 16#1#,
      Green      => 16#2#,
      Cyan       => 16#3#,
      Red        => 16#4#,
      Magenta    => 16#5#,
      Brown      => 16#6#,
      Light_Grey => 16#7#);

   for Background_Colour'Size use 4;

   type Foreground_Colour is
     (Black,
      Blue,
      Green,
      Cyan,
      Red,
      Magenta,
      Brown,
      Light_Grey,
      Dark_Grey,
      Light_Blue,
      Light_Green,
      Light_Cyan,
      Light_Red,
      Light_Magenta,
      Yellow,
      White);

   for Foreground_Colour use
     (Black         => 16#0#,
      Blue          => 16#1#,
      Green         => 16#2#,
      Cyan          => 16#3#,
      Red           => 16#4#,
      Magenta       => 16#5#,
      Brown         => 16#6#,
      Light_Grey    => 16#7#,
      Dark_Grey     => 16#8#,
      Light_Blue    => 16#9#,
      Light_Green   => 16#A#,
      Light_Cyan    => 16#B#,
      Light_Red     => 16#C#,
      Light_Magenta => 16#D#,
      Yellow        => 16#E#,
      White         => 16#F#);

   for Foreground_Colour'Size use 4;

   type Cell_Colour is
      record
         Foreground : Foreground_Colour;
         Background : Background_Colour;
      end record;

   for Cell_Colour use
      record
         Foreground at 0 range 0 .. 3;
         Background at 0 range 4 .. 7;
      end record;

   for Cell_Colour'Size use 8;

   type Cell is
      record
         Char   : Character;
         Colour : Cell_Colour;
      end record;

   for Cell'Size use 16;

   Screen_Width  : constant Natural := 80;
   Screen_Height : constant Natural := 25;

   subtype Screen_Width_Range  is Natural range 1 .. Screen_Width;
   subtype Screen_Height_Range is Natural range 1 .. Screen_Height;

   type Row    is array (Screen_Width_Range)  of Cell;
   type Screen is array (Screen_Height_Range) of Row;

   Video_Memory : Screen;

   for Video_Memory'Address use System'To_Address (16#000B_8000#);

   pragma Import (Ada, Video_Memory);

   procedure Put
     (Char       : in Character;
      X          : in Screen_Width_Range;
      Y          : in Screen_Height_Range;
      Foreground : in Foreground_Colour := White;
      Background : in Background_Colour := Black);

   procedure Put
     (Str        : in String;
      X          : in Screen_Width_Range;
      Y          : in Screen_Height_Range;
      Foreground : in Foreground_Colour := White;
      Background : in Background_Colour := Black);

   procedure Clear (Background : in Background_Colour := Black);
end Console;

console.adb

package body Console is
   procedure Put
     (Char       : in Character;
      X          : in Screen_Width_Range;
      Y          : in Screen_Height_Range;
      Foreground : in Foreground_Colour := White;
      Background : in Background_Colour := Black) is
   begin
      Video_Memory (Y)(X).Char              := Char;
      Video_Memory (Y)(X).Colour.Foreground := Foreground;
      Video_Memory (Y)(X).Colour.Background := Background;
   end Put;

   procedure Put
      (Str        : in String;
       X          : in Screen_Width_Range;
       Y          : in Screen_Height_Range;
       Foreground : in Foreground_Colour := White;
       Background : in Background_Colour := Black) is
   begin
      for Index in Str'First .. Str'Last loop
         Put (Str (Index),
              X + Screen_Width_Range (Index) - 1,
              Y,
              Foreground,
              Background);
      end loop;
   end Put;

   procedure Clear (Background : in Background_Colour := Black) is
   begin
      for X in Screen_Width_Range'First .. Screen_Width_Range'Last loop
         for Y in Screen_Height_Range'First .. Screen_Height_Range'Last loop
            Put (' ', X, Y, Background => Background);
         end loop;
      end loop;
   end Clear;
end Console;

bare_bones.adb

This is platform independent and therefore goes into the src directory.

with Console; use Console;

procedure Bare_Bones is
begin
   Clear;

   Put ("Hello, bare bones in Ada.",
        Screen_Width_Range'First,
        Screen_Height_Range'First);
end Bare_Bones;
pragma No_Return (Bare_Bones);

linker.ld

This is a PC specific script so goes into the src/pc directory.

OUTPUT_FORMAT(elf32-i386)

/* Tell the linker which startup code to use, we do this as there is no way to do this (well not easily) from the GNAT tools. */
STARTUP(startup.o)

ENTRY (startup)

SECTIONS
{
    . = 0x00100000;

    .text :{
        code = .; _code = .; __code = .;
        *(.text)
        *(.rodata)
    }

    .rodata ALIGN (0x1000) : {
        *(.rodata)
    }

    .data ALIGN (0x1000) : {
        data = .; _data = .; __data = .;
        *(.data)
    }

    .bss : {
        sbss = .;
        bss = .; _bss = .; __bss = .;
        *(COMMON)
        *(.bss)
        ebss = .;
    }
    end = .; _end = .; __end = .;
}

makefile

Place this file in the root directory.

ARCH		=	i386
RTS_DIR		=	`pwd`/rts/boards/$(ARCH)

ifeq ($(ARCH),i386)
GPRBUILD	=	gprbuild
AS		=	as
ASFLAGS		=	--32 -march=i386

OBJS		=	obj/startup.o obj/multiboot.o obj/console.o
BOARD		=	pc

.PHONY: obj/multiboot.o obj/console.o

endif

all: bare_bones

bare_bones: $(OBJS) src/bare_bones.adb
	$(GPRBUILD) --RTS=$(RTS_DIR) -XBoard=$(BOARD) -Pbare_bones.gpr

obj/startup.o: src/$(BOARD)/startup.s
	$(AS) $(ASFLAGS) src/$(BOARD)/startup.s -o obj/startup.o

.PHONY: clean

clean:
	-rm obj/* *~ bare_bones

bare_bones.gpr

Place this file in the root directory.

project Bare_Bones is
   type Arch_Name is ("i386", "arm");
   type Board_Name is ("pc", "rpi");

   Arch  : Arch_Name  := "i386";
   Board : Board_Name := external ("Board");

   -- TODO: Add in a case statement that adds an arch dir to source.

   case Board is
      when "pc" =>
         for Source_Dirs use ("src", "src/pc");
      when "rpi" =>
         for Source_Dirs use ("src", "src/rpi");
   end case;

   for Object_Dir use "obj";
   for Exec_Dir use ".";
   for Main use ("bare_bones.adb");

   package Builder is
      Basic_Switches := ("-gnat2005", "-g", "-x", "-a", "-gnatg",
                         "-gnatec=../gnat.adc", "-gnaty-I", "-gnaty+d");

      case Board is
         when "pc" =>
            for Default_Switches ("Ada") use Basic_Switches &
               ("-m32", "-march=i386");
         when "rpi" =>
            for Default_Switches ("Ada") use Basic_Switches &
               ("-march=armv6zk", "-mfpu=vfp", "-mfloat-abi=hard", "-marm",
                "-mcpu=arm1176jzf-s", "-mtune=arm1176jzf-s");
      end case;
   end Builder;

   package Compiler is
      case Board is
         when "pc" =>
            for Default_Switches ("Ada") use
               ("-O0", "-g", "-ggdb", "-ffunction-sections", "-fdata-sections");
         when "rpi" =>
            for Default_Switches ("Ada") use
               ("-O0", "-g", "-ggdb", "-ffunction-sections", "-fdata-sections");

      end case;
   end Compiler;

-- To reduce size of final binary.
   package Linker is
      for Default_Switches ("Ada") use
         ("-Wl,--gc-sections", "-static", "-nostartfiles", "-nodefaultlibs",
          "-T../src/" & Board & "/linker.ld", "-v");
   end Linker;
end Bare_Bones;

Raspberry Pi

Boot process

As stated in [3], the RPi boot proces is as follows:

1. Power on starts the stage 1 boot loader which is on the SoC, which loads the stage 2 boot loader (bootcode.bin) into L2 cache (thus turning it on).
2. bootcode.bin enables SDRAM and loads the stage 3 boot loader (loader.bin).
3. loader.bin loads and executes the VideoCore firmware (start.elf).
4. start.elf loads config.txt, cmdline.txt and kernel.img.

The config.txt file can contain aline "kernel=<name>" where you can name the kernel image anything you like.

Ideally for development we would use an emulator or some kind of netbooting facility so we don't have to keep switching the SD Card from the Pi to the PC and vice versa, this would get tedious really fast.

U-Boot

Seems you need serial access to the board to do this, so I won't be atempting this yet.

By following the information starting on the FreeBSD porting page, we can build u-boot for RPi.

git clone git://github.com/gonzoua/u-boot-pi.git

cd u-boot-pi
make rpi_b_config

Testing

Make sure you have built the RTS above before this next stage otherwise you won't be able to compile the kernel.

make qemu

On the QEMU window, it should clear the screen, the the cursor won't move so it will be in the middle of the screen, in the top-left corner will be the message "Hello, bare bones in Ada."

Source access

I have created a Git repository on GitHub containing the source above so you don't have to do it by hand if you don't want to.

In fact there have ben a lot of changes since I started this project and it is a better idea to grab the source from GitHub as it will be more up to date. I will leave the documents above so you can see how it's evolved and also how it works, maybe a bit clearer that it is now.

Next Steps

A useful next step for further developing the bare bones kernel outlined in this article is implementing capability for using the 'Image attributes on scalar types. This facilitates the printing of integers in string form, which is extremely useful for kernel debugging. A simple guide on how to accomplish this is detailed here.