From ac7d5ef06a6d6e8d84abbd1f0b82162725f98326 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Thu, 11 May 1995 17:39:37 +0000 Subject: Initial revision --- README | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 README (limited to 'README') diff --git a/README b/README new file mode 100644 index 0000000000..02931b8bcb --- /dev/null +++ b/README @@ -0,0 +1,93 @@ +# +# $Id$ +# + +Directory Overview +================== + +This is the top level of the RTEMS directory structure. The following +is a description of the files and directories in this directory: + + INSTALL + Rudimentary installation instructions. For more detailed + information please see the Release Notes. The Postscript + version of this manual can be found in the file + c_or_ada/doc/relnotes.tgz. + + LICENSE + Required legalese. + + README + This file. + + c + This directory contains the source code for the C + implementation of RTEMS as well as the test suites, sample + applications, Board Support Packages, Device Drivers, and + support libraries. + + doc + This directory contains the PDL for the RTEMS executive. + +Ada versus C +============ + +There are two implementations of RTEMS in this source tree -- +in Ada and in C. These two implementations are functionally +and structurally equivalent. The C implementation follows +the packaging conventions and hiearchical nature of the Ada +implementation. In addition, a style has been followed which +allows one to easily find the corresponding Ada and C +implementations. + +File names in C and code placement was carefully designed to insure +a close mapping to the Ada implementation. The following file name +extensions are used: + + .adb - Ada body + .ads - Ada specification + .adp - Ada body requiring preprocessing + .inc - include file for .adp files + + .c - C body (non-inlined routines) + .inl - C body (inlined routines) + .h - C specification + +In the executive source, XYZ.c and XYZ.inl correspond directly to a +single XYZ.adb or XYZ.adp file. A .h file corresponds directly to +the .ads file. There are only a handful of .inc files in the +Ada source and these are used to insure that the desired simple +inline textual expansion is performed. This avoids scoping and +calling convention side-effects in carefully constructed tests +which usually test context switch behavior. + +In addition, in Ada code and data name references are always fully +qualified as PACKAGE.NAME. In C, this convention is followed +by having the package name as part of the name itself and using a +capital letter to indicate the presence of a "." level. So we have +PACKAGE.NAME in Ada and _Package_Name in C. The leading "_" in C +is used to avoid naming conflicts between RTEMS and user variables. +By using these conventions, one can easily compare the C and Ada +implementations. + +The most noticeable difference between the C and Ada83 code is +the inability to easily obtain a "typed pointer" in Ada83. +Using the "&" operator in C yields a pointer with a specific type. +The 'Address attribute is the closest feature in Ada83. This +returns a System.Address and this must be coerced via Unchecked_Conversion +into an access type of the desired type. It is easy to view +System.Address as similar to a "void *" in C, but this is not the case. +A "void *" can be assigned to any other pointer type without an +explicit conversion. + +The solution adopted to this problem was to provide two routines for +each access type in the Ada implementation -- one to convert from +System.Address to the access type and another to go the opposite +direction. This results in code which accomplishes the same thing +as the corresponding C but it is easier to get lost in the clutter +of the apparent subprogram invocations than the "less bulky" +C equivalent. + +A related difference is the types which are only in Ada which are used +for pointers to arrays. These types do not exist and are not needed +in the C implementation. -- cgit v1.2.3