From 7d78d31a52597f1917a55cec274a796317213f65 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 17 Jan 2017 18:27:00 -0600 Subject: c-user: Add Ada support chapter closes #2589. --- c-user/ada_support.rst | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 c-user/ada_support.rst (limited to 'c-user/ada_support.rst') diff --git a/c-user/ada_support.rst b/c-user/ada_support.rst new file mode 100644 index 0000000..9311f93 --- /dev/null +++ b/c-user/ada_support.rst @@ -0,0 +1,92 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1989-2017. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +.. _ada_support + +Ada Support +************ + +.. index:: Ada + +Introduction +============ +RTEMS has long had support for the Ada programming language +by supporting the GNU Ada Compiler (GNAT). There are two primary +components to this support: + +- Ada Programming Language Support + +- Classic API Ada Bindings + +Ada Programming Language Support +================================ + +The Ada programming natively supports multi-threaded programming +with its own tasking and concurrency model. Native Ada multi-threaded +applications should work using GNAT/RTEMS with no changes. + +The application developer will have to account for the specific +requirements of the GNAT Run-Time when configuring RTEMS. There +are example Ada programs with RTEMS configuration and startup sequences. + +Classic API Ada Bindings +======================== + +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. In fact, the top level ``c/`` directory at one point +had a sibling ``ada/``. The current Ada language bindings 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 version of the Classic 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 the context of an interrupt handler. 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. + -- cgit v1.2.3