RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

README: Rewrite and reduce

Browse Source 
Delete old bit-rotting README files and rewrite the README to point
readers toward authoritative sources of documentation.
This commit is contained in:
Gedare Bloom
2013-04-22 13:14:36 -04:00
parent dfd1508168
commit 0ced77e947
3 changed files with 11 additions and 384 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
README
View File

@@ -1,93 +1,15 @@
Building RTEMS
==============
See the file README.configure.
See the documentation manuals in doc/ with daily builds available online at
http://rtems.org/onlinedocs/doc-current/share/rtems/html/ and released builds
at http://www.rtems.org/onlinedocs/releases/
Directory Overview
==================
See the RTEMS Wiki at http://wiki.rtems.org/wiki/index.php/Main_Page
for community knowledge and tutorials.
This is the top level of the RTEMS directory structure. The following
is a description of the files and directories in this directory:
RTEMS Doxygen available at http://www.rtems.org/onlinedocs/doxygen/cpukit/html
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.
Get help on the mailing lists:
* For general-purpose questions related to using RTEMS, use the
rtems-users ml: http://www.rtems.org/mailman/listinfo/rtems-users
* For questions and discussion related to development of RTEMS, use the
rtems-devel ml: http://www.rtems.org/mailman/listinfo/rtems-devel
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 hierarchical 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.

73
README.cdn-X
View File

@@ -1,73 +0,0 @@
Building RTEMS Canadian Cross
=============================
RTEMS now contains experimental and yet incomplete support for building
it Canadian Cross.
1. Introduction
---------------
If you don't know what Canadian Cross Building means, you probably don't want
to apply it and should consider stop reading here.
Interested readers might want to read Ian Lance Taylor's article at
http://www.airs.com/ian/configure for underlaying details and working
principles.
2. RTEMS
--------
Example: Building RTEMS for sparc-rtems under i386-pc-linux-gnu to be hosted
on a i386-cygwin platform.
2.1 Required tools
------------------
* A i386-pc-linux-gnu cross sparc-rtems toolchain.
* A i386-pc-linux-gnu cross i386-cygwin toolchain.
* A i386-pc-linux-gnu native toolchain.
We further on assume these to be installed to these locations:
/opt/rtems .. linux cross sparc-rtems toolchain
/opt/cygwin .. linux cross i386-cygwin cross-toolchain
/usr .. linux native toolchain and further tools.
2.2 Building sparc-rtems
------------------------
The first step is to build RTEMS for sparc-rtems under linux.
mkdir build
cd build
<path>/rtems/configure [options] \
--target=sparc-rtems \
--prefix=/opt/cygwin
make
make install
This will build a standard sparc-rtems RTEMS and install it to the given
PREFIX.
2.3 Building i386-cygwin host support
-------------------------------------
The next step is to build RTEMS host support for i386-cygwin.
This basically means to cross-build the host tools contained in RTEMS.
mkdir host
cd host
<path>/rtems/configure [options] \
--target=sparc-rtems \
--build=`<path>/rtems/config.guess` \
--host=i386-cygwin \
--prefix=/opt/cygwin
make
make install
This will build RTEMS host-tools for i386-cygwin and install them to the given
PREFIX.
3. Known issues
---------------
* At present time, building RTEMS Canadian Cross is known to be immature, and
to require additional work. Do not expect this to work.
* The <toplevel>/make/ directory hierarchy is not treated correctly.

222
README.configure
View File

@@ -1,222 +0,0 @@
1. Autoconf support
===================
This version of RTEMS is configured with GNU autoconf. RTEMS can be
configured and built either standalone or together with the compiler
tools in the Cygnus one-tree structure. Using autoconf also means
that RTEMS now can be built in a separate build directory.
To re-generate auto*tool generated files (configure, Makefile.in etc),
autoconf-2.68 and automake-1.11.1 are required.
2. Installation
===============
To configure RTEMS for a specific target, run configure in the build
directory. In addition to the standard configure options, the following
RTEMS-specific option are supported:
--disable-rtems-inlines
--disable-posix
--disable-networking
--enable-cxx
--enable-multiprocessing
--enable-rtemsbsp="bsp1 bsp2 ..."
--enable-tests
--enable-rdbg (only valid for i386 and some PowerPC BSPs)
--enable-docs
In addition, the following standard autoconf options are frequently
used when configuring RTEMS installations:
--prefix=INSTALL_DIRECTORY
By default, inline routines are used instead of macros where possible.
Macros can be selected using the --disable-inlines option. [NOTE:
Some APIs may not support macro versions of their inline routines.]
By default, the RTEMS POSIX 1003.1b interface is built for targets that support
it. It can be disabled with the --disable-posix option.
By default, the RTEMS networking support is built for targets which
support it. It can be specifically disabled for those targets
with the --disable-networking option.
By default, the RTEMS remote debugger server support is not built.
It can be specifically enabled for the targets that support it.
with the --enable-rdbg option. NB : the RTEMS networking support
must be enabled to support the remote debugger server.
By default, the RTEMS support of C++ is disabled. It can be enabled
with the --enable-cxx option. If the rtems++ C++ library is installed
it will also be build.
By default, the RTEMS test suites are NOT configured -- only the
sample tests are built. --enable-tests will configure
the RTEMS test suite. The default speeds up the build
and configure process when the tests are not desired.
By default, RTEMS is built using arguments and build rules which require a
gcc supporting the -specs option, ie. a gcc >= 2.8.
[The --disable-gcc28 option, which has been present in former releases, has
been removed.]
By default, multiprocessing is is not built. It can be enabled
for those BSPs supporting it by the --enable-multiprocessing option.
By default, all bsps for a target are built. The bare BSP is not built
unless directly specified. There are two ways of changing this:
+ use the --enable-rtemsbsp option which will set the specified
bsps as the default bsps, or
+ set the RTEMS_BSP variable during make (see below).
The --enable-rtemsbsp= option configures RTEMS for a specific board
within a target architecture. Remember that the target specifies the
CPU family while the BSP specifies the precise board you will be using.
The following targets are supported:
arm-rtems4.10
avr-rtems4.10
bfin-rtems4.10
h8300-rtems4.10
i386-rtems4.10
lm32-rtems4.10
m32c-rtems4.10
m32r-rtems4.10
m68k-rtems4.10
mips-rtems4.10
no_cpu-rtems4.10
powerpc-rtems4.10
sh-rtems4.10
sparc-rtems4.10
The cross-compiler is set to $(target)-gcc by default.
To build, run make in the build directory. To specify which bsps to build,
add the RTEMS_BSP="bsp1 bsp2 .." to the make command. Specifying multiple
BSPs to build only works from the top level build directory.
Installation is done under $(prefix)/rtems.
As an example, to build and install the mvme136 and mvme162 bsps for m68k do:
(path_to_rtems_src)/configure --target=m68k-rtems4.11
make RTEMS_BSP="mvme136 mvme162"
make install RTEMS_BSP="mvme136 mvme162"
The sample tests are built by 'make all' when configured with
--enable-tests=samples. Use --enable-tests=all to build the full
test suite.
Documentation is built separately from the source code.
3. To use the installed RTEMS library
=====================================
To use the installed RTEMS bsps to build applications, the application
makefile has to include a bsp-specific makefile that will define the
RTEMS variables necessary to find include files and libraries. The
bsp-specific makefile is installed at
$(RTEMS_MAKEFILE_PATH)/Makefile.inc
For the erc32 bsp installed at /usr/local/cross, the environment
variable RTEMS_MAKEFILE_PATH would be set as follows to the
following:
/usr/local/cross/sparc-rtems/rtems/erc32/Makefile.inc
4. Supported target bsps
========================
The following bsps are supported:
arm : csb336 csb337 edb7312 gba gp32 nds rtl22x rtl22xx_t
smdk2410
avr: : avrtest
bfin : eZKit533 bf537Stamp
h8300 : h8sim
i386 : i386ex pc386 pc386dx pc486 pc586 pc686 pck6 ts_386ex
NOTE: The "pc386" BSP can be compiled to support a
variety of PC configurations including PC-104
based solutions.
lm32: : lm32_evr
m32c : m32csim
m32r : m32rsim
m68k : av5282 csb360 gen68302 gen68360 gen68360_040
genmcf548x idp mcf5206elite mcf52235 mcf5235 mcf5239
m5484FireEngine mrm332 mvme136 mvme147s mvme162 mvme162lx
mvme167 ods68302 pgh360 sim68000 simcpu32 uC5282 COBRA5475
no_cpu : no_bsp (porting example)
mips : csb350 genmongoosev hurricane jmr3904 rbtx4925 rbtx4938
p4600 p4650
powerpc : brs5l ep1a gen5200 gen83xx haleakala hsc_cm01 icecube
mbx821_001 mbx821_002 mbx821_002b mbx860_001b mbx860_002
mbx860_005b mcp750 mvme2100 mvme2307 mtx603e
mvme5500 mpc55xxevb mpc8260ads mpc8313erdb mpc8349eamds
pghplus pm520_cr825 pm520_ze30 psim score603e ss555
tqm8xx_stk8xx virtex
NOTE: The "motorola_powerpc" BSP is a single BSP which
can be conditionally compiled to support most Motorola
VMEbus, CompactPCI, and MTX boards.)
NOTE: The mbx8xx, gen5200, gen83xx, and tqm8xx BSPs are
designed to handle a variety of boards based on the same
family of system on chips CPUs
sh : gensh1 gensh2 gensh4 simsh1 simsh2 simsh4
sparc : erc32 sis leon2 leon3
5. Makefile structure
=====================
The makefiles have been re-organized. Most gnu-based bsps now use three
main makefiles:
+ custom/default.cfg,
+ custom/bsp.cfg and
+ compilers/gcc-target-default.cfg.
Default.cfg sets the default values of certain common build options.
Bsp.cfg set bsp-specific build options and can also override the
default settings.
Gcc-target-default.cfg contains the common gcc definitions.
6. Adding a bsp
===============
Please refer to the BSP and Device Driver Guide.
7. Tested configurations
========================
All gnu-based bsps have been built on Linux.
8. Prerequisites
================
Gawk version 2 or higher.
GNU make version 3.72 or higher.
Bash.
gcc version > 2.8
NOTE: These prerequisites are probably out of date but autoconf should detect
any problems.