Update Applications Ada User's Guide

[Chris Johns]

Update the Applications Ada User's Guide to REST format.

[Joel Sherrill]

Turning into a chapter in C User's Guide to describe the binding rules, location in source tree, etc. If it is more than 2 pages, then something is wrong.

[Joel Sherrill]

This should be a good first cut at a chapter in the C User's Guide to replace the Ada User's Guide build variant.

============================================

An Ada language binding exists for a subset of the RTEMS Classic API. In the early 1990's, there were C and Ada implementations of RTEMS which were functionally equivalent. The source structure was as similar as possible. This binding and test code was derived from that Ada implementation.

The Ada binding specifically excludes some methods which are either not safe or not intended for use from Ada programs. However, methods are generally only added to this binding when a user makes a requests. Thus some methods that could be supported are not. If in doubt, ask about a methods and contribute bindings.

The bindings are located in the c/src/ada directory of the RTEMS source tree. The tests are in c/src/ada-tests.

The bindings following a simple pattern to map the C Classic API calls into Ada subprograms. The following rules are used:

• All RTEMS interfaces are in the RTEMS Ada package. The rtems_ and RTEMS_ prefixes in the C API thus correspond to "RTEMS." in Ada symbol nomenclature. For example, rtems_task_create() in C is RTEMS.Task_Create() in Ada.
• Classic API directives tend to return an rtems_status_code. Some directives also have an output parameter such as an object id on a create operation. Ada subprograms are either pure functions with only a single return value or subprograms. For consistency, the returned status code is always the last parameter of the Ada calling sequence.

Caution should be exercised when writing programs which mix Ada tasks, Classic API tasks, and POSIX API threads. Ada tasks use a priority numbering scheme defined by the Ada programming language. Each Ada task is implemented in GNAT/RTEMS as a single POSIX thread. Thus Ada task priorities must be mapped onto POSIX thread priorities. Complicating matters, Classic API tasks and POSIX API threads use different numbering schemes for priority. Low numbers are high priority in the Classic API while indicating low priority in the POSIX threads API. Experience writing mixed threading model programs teaches that creating a table of the priorities used in the application with the value in all tasking models used is helpful.

The GNAT run-time uses a priority ceiling mutex to protect its data structures. The priority ceiling value is one priority more important than the most important Ada task priority (in POSIX API terms). Do not invoke any services implemented in Ada from a thread or task which is of greater priority. This will result in a priority ceiling violation error and lead to a failure in the Ada run-time.

Exercise extreme caution when considering writing code in Ada which will execute in an hardware interrupt context. Hardware interrupts are processed outside the context of any thread in RTEMS and this can lead to violating assumptions in the GNAT run-time. Specifically a priority ceiling mutex should never be used from an ISR and it is difficult to predict when the Ada compiler or run-time will use a mutex.

[Chris Johns]

Please update the user guide or close this ticket.

[Joel Sherrill]

This was closed by the commit:

​https://git.rtems.org/rtems-docs/commit/?id=7d78d31a52597f1917a55cec274a796317213f65

Any enhancements or corrections to that chapter should go in another ticket.