source: rtems/README @ 87a95526

4.104.114.84.9
Last change on this file since 87a95526 was f9e72d3, checked in by Joel Sherrill <joel.sherrill@…>, on Sep 1, 2000 at 7:19:16 AM

2000-08-31 Ralf Corsepius <corsepiu@…>

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