Documenting the technical aspects and development of a GNAT/RTS

Projects Award Nominations
, ,
1

Documenting the technical aspects and development of a GNAT/RTS

The Ada Awards Committee has nominated for an award the task of documenting the technical aspects and development of the Ada RTS. This proposal has been motivated by the following community posts and work:

Motivation

Currently, the documentation on how to write a GNAT Ada Runtime System (RTS) is sparse to say the least. Searching up information will yield the osdev.wiki articles on the Ada runtime library which are a bit dated and not that exhaustive. There are also GNAT’s source code for various systems (eg. Linux/Windows/embedded and more) and community libraries that add Ada support to boards or other systems. However the source code only explains some of its design decisions in comments and does not explain the general design of the RTS, what is required for the different levels of support, how different platform are tackled and specifically how to make your own runtime. Other than the aforementioned sources, there are next to no other well written documents on how to write your own Ada RTS.

Goals

The final deliverable is a well-written and comprehensive document that explains, from beginning to end, the Ada RTS and how one is implemented. This document will have to be formatted such that it can be added to Ada-Lang’s website and potentially to Learn.AdaCore as a technical guide.

The Documentation has to be written in the KISS (Keep It Simple Stupid) style to make it accessible for newcomers to RTSes and give them a solid base to write their own runtime. Therefore, it has to be as generic as possible: the explanations should be as platform independent as possible. References to projects are encouraged and code reuse is also encouraged. Code snippets, examples, etc; are required.

The Ada Awards Committee would like to use the Ada on the Casio fx-CG50 as the experimental baseline for this kind of task, but other approaches can also be discussed. The fx-CG50 calculator uses a fairly old architecture with a revered-engineered OS/low-level library. This strikes a nice balance between being low-level, high-level and an interesting marketable example for Ada’s flexibility.

Non-exhaustive list of resources

  • SweetAda: a large, embedded framework to run Ada programs on a large number of boards and architectures. It does not use any underlying OS or library.
  • ada-runtime: small and portable runtime that has substantial parts verified in SPARK.
  • bare_runtime: a minimalAda/SPARK run-time for embedded or other restricted targets.
  • ESP-IDF GNAT Runtime: an Ada RTS based on Espressif system libraries.
  • FreeRTOS-Ada: a GNAT Ada runtime for an embedded RTOS.
  • Ironclad’s own RTS: the Ada RTS for the Ironclad kernel.
  • GNAT’s own RTSes (and the Makefile: the RTSes that are present inside GNAT for different Operating Systems such as Windows, Mac and Linux.

Milestones

Part 1 (Award: 100 EUR)

  • Brief introduction to the Ada RTS.
  • Differences between an RTS based on pure hardware, on a small (RT)OS or system library and those on top of full OSes (Linux, Windows…).
  • Explanation of the major parts of the Ada RTS:
    • System package and its children
    • Non-tasking modules
      • Specific section about memory management
        • Storage Pools
        • Secondary Stack
    • Tasking modules
      • Profiles (Ravenscar, Jorvik)
      • Protected objects
      • Limitations of the profiles w.r.t a full tasking profile
      • Different strategies to implement tasking (work stealing, cooperative, etc)

The points above should be generic in nature and serve as a general introduction. Small, generic code examples should be provided (e.g. what is allowed and not allowed depending on the RTS, what can or cannot be done depending on the modules that the RTS implements). Cross referencing between the points above and those below is greatly encouraged.

Part 2 (Award: 200 EUR)

  • How to build a full GNAT (or GNAT-LLVM) toolchain for a given target to develop an RTS.
  • Implementing parts of an RTS:
    • Implementing a timer for the delay keyword (a simple start that is easy to test + examples on the Casio calculator and on Zephyr RTOS).
    • Error handling and last_chance_handler (fallback and explanation on Ada Exceptions.)
    • Light-tasking
    • Memory management, storage pools and secondary stack (explanation between stack and heap, memory addresses of target system, design behind pools and uses of the secondary stack.)
    • Handling the filesystem and files
    • Testing the ACATS test suite on the custom runtime.
  • Packaging the Runtime for Alire and how to use the custom runtime with GNAT.

Guidelines and further indications

The general Ada Awards Guidelines apply to this proposal for those who want to participate. For open, technical discussions on this topic or project, feel free to open topics under the Active Projects forum category.

Best regards,
The Ada Awards Committee.

7 Likes
2

Well, I already documented a zfs like rts on osdev.org years ago and someone else wrote another article on there. Mine needs to be updated, but could be used as a basis.

2 Likes
3

I actually used your article as a guide! It helped me a lot to get started but there are no further guides on how and where to continue. Having to implement (and read and understand) the entire Ada RM feels daunting as a beginner. And that’s something I want to improve upon!

3 Likes