Changeset 0ced77e9 in rtems

Apr 22, 2013, 5:14:36 PM (6 years ago)
Gedare Bloom <gedare@…>
4.11, master
Gedare Bloom <gedare@…> (04/22/13 17:14:36)
Gedare Bloom <gedare@…> (04/23/13 13:06:41)

README: Rewrite and reduce

Delete old bit-rotting README files and rewrite the README to point
readers toward authoritative sources of documentation.

2 deleted
1 edited



    rdfd1508 r0ced77e9  
    1 Building RTEMS
    2 ==============
    3 See the file README.configure.
     1See the documentation manuals in doc/ with daily builds available online at
     2 and released builds
    5 Directory Overview
    6 ==================
     5See the RTEMS Wiki at
     6for community knowledge and tutorials.
    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:
     8RTEMS Doxygen available at
    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.
     10Get help on the mailing lists:
     11* For general-purpose questions related to using RTEMS, use the
     12  rtems-users ml:
     13* For questions and discussion related to development of RTEMS, use the
     14  rtems-devel ml:
    17   LICENSE
    18     Required legalese.
    20   README
    21     This file.
    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.
    29   doc
    30     This directory contains the PDL for the RTEMS executive.
    32 Ada versus C
    33 ============
    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 hierarchical 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. 
    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:
    47    .adb - Ada body
    48    .ads - Ada specification
    49    .adp - Ada body requiring preprocessing
    50    .inc - include file for .adp files
    52    .c   - C body (non-inlined routines)
    53    .inl - C body (inlined routines)
    54    .h   - C specification
    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.
    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.
    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. 
    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.
    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.
Note: See TracChangeset for help on using the changeset viewer.