summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJoel Sherrill <joel@rtems.org>2017-01-18 00:27:00 (UTC)
committerJoel Sherrill <joel@rtems.org>2017-01-18 00:28:05 (UTC)
commit7d78d31a52597f1917a55cec274a796317213f65 (patch)
tree313c9d92bd1ada89772e416c241d8e359865f8f9
parent23b1c1088ec595c2ca61435c4775ff9797e121a4 (diff)
downloadrtems-docs-7d78d31a52597f1917a55cec274a796317213f65.tar.bz2
c-user: Add Ada support chapter
closes #2589.
-rw-r--r--c-user/ada_support.rst92
-rw-r--r--c-user/index.rst1
2 files changed, 93 insertions, 0 deletions
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.
+
diff --git a/c-user/index.rst b/c-user/index.rst
index 4aa267d..f458e59 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -72,6 +72,7 @@ to the Community Project hosted at http://www.rtems.org/.
red_black_trees
timespec_helpers
constant_bandwidth_server
+ ada_support
directive_status_codes
linker_sets
example_application