[rtems-docs commit] c-user: Add Ada support chapter

[Joel Sherrill]

Module:    rtems-docs
Branch:    master
Commit:    7d78d31a52597f1917a55cec274a796317213f65
Changeset: http://git.rtems.org/rtems-docs/commit/?id=7d78d31a52597f1917a55cec274a796317213f65

Author:    Joel Sherrill <joel at rtems.org>
Date:      Tue Jan 17 18:27:00 2017 -0600

c-user: Add Ada support chapter

closes #2589.

---

 c-user/ada_support.rst | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++
 c-user/index.rst       |  1 +
 2 files changed, 93 insertions(+)

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