1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. COMMENT: COPYRIGHT (c) 1989-2017. |
---|
4 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
5 | .. COMMENT: All rights reserved. |
---|
6 | |
---|
7 | .. _ada_support |
---|
8 | |
---|
9 | Ada Support |
---|
10 | ************ |
---|
11 | |
---|
12 | .. index:: Ada |
---|
13 | |
---|
14 | Introduction |
---|
15 | ============ |
---|
16 | RTEMS has long had support for the Ada programming language |
---|
17 | by supporting the GNU Ada Compiler (GNAT). There are two primary |
---|
18 | components to this support: |
---|
19 | |
---|
20 | - Ada Programming Language Support |
---|
21 | |
---|
22 | - Classic API Ada Bindings |
---|
23 | |
---|
24 | Ada Programming Language Support |
---|
25 | ================================ |
---|
26 | |
---|
27 | The Ada programming natively supports multi-threaded programming |
---|
28 | with its own tasking and concurrency model. Native Ada multi-threaded |
---|
29 | applications should work using GNAT/RTEMS with no changes. |
---|
30 | |
---|
31 | The application developer will have to account for the specific |
---|
32 | requirements of the GNAT Run-Time when configuring RTEMS. There |
---|
33 | are example Ada programs with RTEMS configuration and startup sequences. |
---|
34 | |
---|
35 | Classic API Ada Bindings |
---|
36 | ======================== |
---|
37 | |
---|
38 | An Ada language binding exists for a subset of the RTEMS Classic |
---|
39 | API. In the early 1990's, there were C and Ada implementations of |
---|
40 | RTEMS which were functionally equivalent. The source structure was as |
---|
41 | similar as possible. In fact, the top level ``c/`` directory at one point |
---|
42 | had a sibling ``ada/``. The current Ada language bindings and test code was |
---|
43 | derived from that Ada implementation. |
---|
44 | |
---|
45 | The Ada binding specifically excludes some methods which are either not |
---|
46 | safe or not intended for use from Ada programs. However, methods are |
---|
47 | generally only added to this binding when a user makes a requests. Thus |
---|
48 | some methods that could be supported are not. If in doubt, ask about a |
---|
49 | methods and contribute bindings. |
---|
50 | |
---|
51 | The bindings are located in the ``c/src/ada`` directory of the RTEMS source |
---|
52 | tree. The tests are in ``c/src/ada-tests``. The bindings following a simple |
---|
53 | pattern to map the C Classic API calls into Ada subprograms. The following |
---|
54 | rules are used: |
---|
55 | |
---|
56 | - All RTEMS interfaces are in the RTEMS Ada package. The rtems\_ and |
---|
57 | RTEMS\_ prefixes in the C version of the Classic API thus correspond to |
---|
58 | "RTEMS." in Ada symbol nomenclature. For example, ``rtems_task_create()`` |
---|
59 | in C is ``RTEMS.Task_Create()`` in Ada. |
---|
60 | |
---|
61 | - Classic API directives tend to return an ``rtems_status_code``. Some |
---|
62 | directives also have an output parameter such as an object id on a create |
---|
63 | operation. Ada subprograms are either pure functions with only a single |
---|
64 | return value or subprograms. For consistency, the returned status code |
---|
65 | is always the last parameter of the Ada calling sequence. |
---|
66 | |
---|
67 | Caution should be exercised when writing programs which mix Ada tasks, |
---|
68 | Classic API tasks, and POSIX API threads. Ada tasks use a priority |
---|
69 | numbering scheme defined by the Ada programming language. Each Ada task |
---|
70 | is implemented in GNAT/RTEMS as a single POSIX thread. Thus Ada task |
---|
71 | priorities must be mapped onto POSIX thread priorities. Complicating |
---|
72 | matters, Classic API tasks and POSIX API threads use different numbering |
---|
73 | schemes for priority. Low numbers are high priority in the Classic |
---|
74 | API while indicating low priority in the POSIX threads API. Experience |
---|
75 | writing mixed threading model programs teaches that creating a table |
---|
76 | of the priorities used in the application with the value in all tasking |
---|
77 | models used is helpful. |
---|
78 | |
---|
79 | The GNAT run-time uses a priority ceiling mutex to protect its data |
---|
80 | structures. The priority ceiling value is one priority more important |
---|
81 | than the most important Ada task priority (in POSIX API terms). Do not |
---|
82 | invoke any services implemented in Ada from a thread or task which is |
---|
83 | of greater priority. This will result in a priority ceiling violation |
---|
84 | error and lead to a failure in the Ada run-time. |
---|
85 | |
---|
86 | Exercise extreme caution when considering writing code in Ada which |
---|
87 | will execute in the context of an interrupt handler. Hardware interrupts are |
---|
88 | processed outside the context of any thread in RTEMS and this can lead |
---|
89 | to violating assumptions in the GNAT run-time. Specifically a priority |
---|
90 | ceiling mutex should never be used from an ISR and it is difficult to |
---|
91 | predict when the Ada compiler or run-time will use a mutex. |
---|
92 | |
---|
93 | RTEMS has two capabilities which can assist in avoiding this problem. The |
---|
94 | Classic API Timer Manager allows the creation of Timer Service Routines |
---|
95 | which execute in the context of a task rather than the clock tick |
---|
96 | Interrupt Service Routine. Similarly, there is support for Interrupt Tasks |
---|
97 | which is a mechanism to defer the processing of the event from the |
---|
98 | hardware interrupt level to a thread. |
---|
99 | |
---|