[ac7d5ef0] | 1 | # |
---|
| 2 | # $Id$ |
---|
| 3 | # |
---|
| 4 | |
---|
| 5 | Directory Overview |
---|
| 6 | ================== |
---|
| 7 | |
---|
| 8 | This is the top level of the RTEMS directory structure. The following |
---|
| 9 | is a description of the files and directories in this directory: |
---|
| 10 | |
---|
| 11 | INSTALL |
---|
| 12 | Rudimentary installation instructions. For more detailed |
---|
| 13 | information please see the Release Notes. The Postscript |
---|
| 14 | version of this manual can be found in the file |
---|
| 15 | c_or_ada/doc/relnotes.tgz. |
---|
| 16 | |
---|
| 17 | LICENSE |
---|
| 18 | Required legalese. |
---|
| 19 | |
---|
| 20 | README |
---|
| 21 | This file. |
---|
| 22 | |
---|
| 23 | c |
---|
| 24 | This directory contains the source code for the C |
---|
| 25 | implementation of RTEMS as well as the test suites, sample |
---|
| 26 | applications, Board Support Packages, Device Drivers, and |
---|
| 27 | support libraries. |
---|
| 28 | |
---|
| 29 | doc |
---|
| 30 | This directory contains the PDL for the RTEMS executive. |
---|
| 31 | |
---|
| 32 | Ada versus C |
---|
| 33 | ============ |
---|
| 34 | |
---|
| 35 | There are two implementations of RTEMS in this source tree -- |
---|
| 36 | in Ada and in C. These two implementations are functionally |
---|
| 37 | and structurally equivalent. The C implementation follows |
---|
| 38 | the packaging conventions and hiearchical nature of the Ada |
---|
| 39 | implementation. In addition, a style has been followed which |
---|
| 40 | allows one to easily find the corresponding Ada and C |
---|
| 41 | implementations. |
---|
| 42 | |
---|
| 43 | File names in C and code placement was carefully designed to insure |
---|
| 44 | a close mapping to the Ada implementation. The following file name |
---|
| 45 | extensions are used: |
---|
| 46 | |
---|
| 47 | .adb - Ada body |
---|
| 48 | .ads - Ada specification |
---|
| 49 | .adp - Ada body requiring preprocessing |
---|
| 50 | .inc - include file for .adp files |
---|
| 51 | |
---|
| 52 | .c - C body (non-inlined routines) |
---|
| 53 | .inl - C body (inlined routines) |
---|
| 54 | .h - C specification |
---|
| 55 | |
---|
| 56 | In the executive source, XYZ.c and XYZ.inl correspond directly to a |
---|
| 57 | single XYZ.adb or XYZ.adp file. A .h file corresponds directly to |
---|
| 58 | the .ads file. There are only a handful of .inc files in the |
---|
| 59 | Ada source and these are used to insure that the desired simple |
---|
| 60 | inline textual expansion is performed. This avoids scoping and |
---|
| 61 | calling convention side-effects in carefully constructed tests |
---|
| 62 | which usually test context switch behavior. |
---|
| 63 | |
---|
| 64 | In addition, in Ada code and data name references are always fully |
---|
| 65 | qualified as PACKAGE.NAME. In C, this convention is followed |
---|
| 66 | by having the package name as part of the name itself and using a |
---|
| 67 | capital letter to indicate the presence of a "." level. So we have |
---|
| 68 | PACKAGE.NAME in Ada and _Package_Name in C. The leading "_" in C |
---|
| 69 | is used to avoid naming conflicts between RTEMS and user variables. |
---|
| 70 | By using these conventions, one can easily compare the C and Ada |
---|
| 71 | implementations. |
---|
| 72 | |
---|
| 73 | The most noticeable difference between the C and Ada83 code is |
---|
| 74 | the inability to easily obtain a "typed pointer" in Ada83. |
---|
| 75 | Using the "&" operator in C yields a pointer with a specific type. |
---|
| 76 | The 'Address attribute is the closest feature in Ada83. This |
---|
| 77 | returns a System.Address and this must be coerced via Unchecked_Conversion |
---|
| 78 | into an access type of the desired type. It is easy to view |
---|
| 79 | System.Address as similar to a "void *" in C, but this is not the case. |
---|
| 80 | A "void *" can be assigned to any other pointer type without an |
---|
| 81 | explicit conversion. |
---|
| 82 | |
---|
| 83 | The solution adopted to this problem was to provide two routines for |
---|
| 84 | each access type in the Ada implementation -- one to convert from |
---|
| 85 | System.Address to the access type and another to go the opposite |
---|
| 86 | direction. This results in code which accomplishes the same thing |
---|
| 87 | as the corresponding C but it is easier to get lost in the clutter |
---|
| 88 | of the apparent subprogram invocations than the "less bulky" |
---|
| 89 | C equivalent. |
---|
| 90 | |
---|
| 91 | A related difference is the types which are only in Ada which are used |
---|
| 92 | for pointers to arrays. These types do not exist and are not needed |
---|
| 93 | in the C implementation. |
---|