diff --git a/wiki/CompilerIssues.txt b/wiki/CompilerIssues.txt deleted file mode 100644 index eca6424..0000000 --- a/wiki/CompilerIssues.txt +++ /dev/null @@ -1,54 +0,0 @@ -[TOC] - ----- - -There are some source code constructs that, while perfectly legal and working under desktop compilations, cause errors with this RTS. This is probably caused by misunderstanding of the exact interface between the compiler and the RTS, which is complex (to put it mildly). - -Compiler mistakes restriction violation [tickets:11] -==== - -A package containing an instantiation of `Ada.Containers.Bounded_Vectors` couldn’t be linked because the compiler (GCC 4.9.1 and GNAT GPL 2014) had mistakenly decided that it violated the restriction `No_Implicit_Heap_Allocations` (which is part of the Ravenscar profile). - -GCC 5.0.0 doesn’t have this error. - -A workround (which allowed the package which revealed the problem to be built) was to explicitly state the restriction in the body: - - :::ada - pragma Restrictions (No_Implicit_Heap_Allocations); - - with Ada.Containers.Bounded_Vectors; - - package body Containing is - - subtype Index is Natural range 0 .. 19; - subtype Line is String (1 .. 20); - - package Line_Vectors - is new Ada.Containers.Bounded_Vectors (Index_Type => Index, - Element_Type => Line); - -`Attach_Handler` must be in pragma form -==== - -In this code - - :::ada - protected Button - with - Interrupt_Priority => System.Interrupt_Priority'First - is - entry Wait_For_Trigger; - private - Triggered : Boolean := False; - procedure Handler; - pragma Attach_Handler (Handler, Ada.Interrupts.Names.EXTI0_IRQ); - end Button; - -you would have liked to attach the handler using the aspect syntax, - - :::ada - procedure Handler - with - Attach_Handler => Ada.Interrupts.Names.EXTI0_IRQ; - -but this doesn’t work in GCC 4.9.1 (it’s OK in GNAT GPL 2014 & GCC 5.0.0). diff --git a/wiki/ExceptionHandling.txt b/wiki/ExceptionHandling.txt deleted file mode 100644 index 3f5cbc1..0000000 --- a/wiki/ExceptionHandling.txt +++ /dev/null @@ -1,49 +0,0 @@ -This RTS has the restriction `No_Exception_Propagation`. - -This means that any unhandled exception in a subprogram will immediately result in a call to `Last_Chance_Handler`, which won't return. - -Also, you can't use the `raise` statement to do partial handling, as in - - :::ada - declare - Err : exception; - begin - begin - raise Err with "test"; - exception - when Err => - -- partial cleanup - raise; -- this is not permitted - end; - exception - when Err => null; -- this is OK - end; - -The RTS's last chance exception handler is written as - - :::c - __attribute__((weak)) - void __gnat_last_chance_handler(const char *message, int line) { - taskDISABLE_INTERRUPTS(); - vTaskSuspendAll(); - // Loop indefinitely: use the debugger to examine the backtrace. - while (1) {} - } - -and the `weak` attribute means that you can write your own version to do something more immediately useful, provided it matches the spec - - :::ada - procedure Last_Chance_Handler - (Message : System.Address; Line : Integer) - with - Export, - Convention => C, - External_Name => "__gnat_last_chance_handler"; - -(but it's much easier to read the exception message in the debugger if you use the C version) - -Note that at the moment the `Line` parameter is always `0` (this may be affected by the *binder* argument `-E`). - -# What about full exception handling? - -I've made several attempts to support exception handling; unfortunately, it's spread throughout the RTS and requires introducing and modifying many packages. I take some heart from the late Robert Dewar's remarks starting [here](https://www.youtube.com/watch?v=0yXwnk8Cr0c) at 16:20 - "exceptions are a huge pain in the neck to implement". diff --git a/wiki/Finalization.txt b/wiki/Finalization.txt deleted file mode 100644 index 2a39a8c..0000000 --- a/wiki/Finalization.txt +++ /dev/null @@ -1,11 +0,0 @@ -This RTS has the restriction `No_Finalization`, which means that package `Ada.Finalization` can't be included (or, of course, used). - -Originally, this was because it was later on the development path. However, when I attempted it (on branch `Finalization`) there were two compiler-related issues: - -* [PR66242](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66242), "Front-end error if exception propagation disabled" and finalization isn't. This has been corrected in GNAT GPL 2016 and FSF GCC 6.1.0. - -* [PR66205](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66205), "gnatbind generates invalid code when finalization is enabled in restricted runtime". This has not been fixed (though I did provide a patch, see the PR). - -For PR66205, I pursued the idea of front- (or, perhaps, back-)ending the GCC-provided *gnatbind* with something to fix up the generated code. This seems difficult with *gprbuild*. - -The main consequence of this is that the provided `Ada.Containers` code has had the dependence on finalization removed; this meant that the tampering checks also had to be removed. diff --git a/wiki/FindingAnRTS.txt b/wiki/FindingAnRTS.txt deleted file mode 100644 index 51aab1e..0000000 --- a/wiki/FindingAnRTS.txt +++ /dev/null @@ -1,58 +0,0 @@ -The GNAT compiler running under gprbuild can find RTSs in various ways. An RTS usually contains an `adainclude/` directory with the source of the RTS and an `adalib/` directory with the corresponding library, linker script and `.ali` files (these defaults can be changed by listing the source directory, or colon-separated directories, in `ada_source_path`, and the object directory in `ada_object_path`). - -If not the default, the RTS can be named on the command using a `--RTS=` option. In a GPR, you can do this in package Builder (so it's applied during all phases of the build): - - package Builder is - for Default_Switches ("ada") use - ( - "-g", - "-O0", - "--RTS=stm32f429i" - ); - end Builder; - -or, with GPRBUILD GPL 2015 or later, via an attribute: - - for Runtime ("ada") use "stm32f429i"; - -There are two places where RTSs can be installed: - -* in the location indicated by `arm-eabi-gcc -print-libgcc-file-name`; for GNAT GPL 2015, that would be `$prefix/lib/gcc/arm-eabi/4.9.4/`, referred to from here as `$lib`. -* in `$prefix/arm-eabi/lib/gnat`. - -You can also work with an RTS in its build location. - -In `$lib`: ----- - -The directory containing the RTS should be called `rts-{name}`, for example `rts-stm32f429i`. - -If the RTS is named `stm32f429i`, the compiler will treat it as the default RTS (and you need a default RTS) if - -* `$lib` contains text files `ada_object_path`, `ada_source_path` containing the locations of the `adalib` and `adainclude` directories of the RTS respectively, and (GCC 5.0) there is a file `adainclude/system.ads`; or -* `$lib` contains symbolic links named `adalib` and `adainclude` to the `adalib` and `adainclude` directories of the RTS respectively. - -Alternative RTSs are found here if they are in directories named `rts-{name}`, for example `rts-stm32f429i/` corresponds to `--RTS=stm32f429i`. - -In `$prefix/arm-eabi/lib/gnat`: ----- - -The directory containing the RTS is just called `{name}`, e.g. `stm32f429i`. - -In the build location: ----- - -RTSs can also be located by giving the explicit path in the `Runtime ("ada")` attribute or the `--RTS=` option (this has to be an absolute path with GPRBUILD GPL 2015): - - package Builder is - for Default_Switches ("ada") use - ( - "-g", - "-O0", - "--RTS=“ & Project’Project_Dir & "../stm32f429i" - ); - end Builder; - -or - - for Runtime ("ada") use Project’Project_Dir & "../stm32f429i"; diff --git a/wiki/Home.txt b/wiki/Home.txt deleted file mode 100644 index e01e05a..0000000 --- a/wiki/Home.txt +++ /dev/null @@ -1,11 +0,0 @@ -This wiki contains information which may be useful to developers using the RTSs and to other maintainers. - -* [Finding an RTS](FindingAnRTS) -* [Secondary Stack](SecondaryStack) -* [Exception Handling](ExceptionHandling) -* [Finalization](Finalization) -* [Outstanding Problems](OutstandingProblems) -* [Compiler Issues](CompilerIssues) -* [Working with GNAT GPL](WorkingWithGnatGPL) - - diff --git a/wiki/OutstandingProblems.txt b/wiki/OutstandingProblems.txt deleted file mode 100644 index 59277cd..0000000 --- a/wiki/OutstandingProblems.txt +++ /dev/null @@ -1,6 +0,0 @@ -[TOC] - -*** - -(none) ----- diff --git a/wiki/SecondaryStack.txt b/wiki/SecondaryStack.txt deleted file mode 100644 index cb4d0c6..0000000 --- a/wiki/SecondaryStack.txt +++ /dev/null @@ -1,24 +0,0 @@ -The *secondary stack* is what GNAT uses to manage functions which return objects of an indefinite type: for example, - - :::ada - function F return String; - -Desktop GNAT manages the secondary stack in the heap, so that it can be of unbounded size. This implementation, however, manages it by carving out a proportion of each task’s stack; currently this is 10%, but this can be altered globally in `System.Parameters` (`s-parame.adb`) in function `Secondary_Stack_Size`: - - :::ada - function Secondary_Stack_Size (Stack_Size : Size_Type) return Size_Type - is ((Stack_Size * 10) / 100); - -If you have a function returning a large indefinite type (a long `String`, say, or an indefinite array of large objects), you’ll need to allocate a larger stack for the using task: - - :::ada - task type T - with - Storage_Size => 10_000 - is - end T; - -Note: - -* `Storage_Error` will be raised if you try to use more secondary stack than is available. -* The main program's secondary stack has size 256 (see `s-secsta.adb` if you need to change this). diff --git a/wiki/WorkingWithGnatGPL.txt b/wiki/WorkingWithGnatGPL.txt deleted file mode 100644 index 6b245d0..0000000 --- a/wiki/WorkingWithGnatGPL.txt +++ /dev/null @@ -1,25 +0,0 @@ -C library -==== - -These RTSs need a C library. The GNAT GPL cross-compiler as supplied by AdaCore for Linux and Windows doesn't include a C library, so you'll need to build your own and install it. These instructions are for Linux; for Windows, at least the `--prefix` setting will need to change to match your compiler. - -Obtain [Newlib](https://sourceware.org/newlib/), unpack it into `newlib-2.2.0` (or later version, of course). You'll need to build in a parallel directory (in other words, *don't* `configure` in the source directory!). Assuming your GNAT GPL 2016 compiler is installed at /opt/gnat-gpl-2016, - - mkdir newlib-2.2.0-build - cd newlib-2.2.0-build - ../newlib-2.2.0/configure \ - --build=x86_64-pc-linux-gnu \ - --target=arm-eabi \ - --prefix=/opt/gnat-gpl-2016 \ - --with-arch=armv7 \ - --with-mode-thumb \ - --enable-multilib \ - --with-gnu-as \ - --with-gnu-ld \ - --disable-nls \ - --disable-newlib-supplied-syscalls - -and then make and install: - - $ make - $ sudo make install