[PATCH] README: Rewrite and reduce
Gedare Bloom
gedare at rtems.org
Mon Apr 22 17:18:57 UTC 2013
Delete old bit-rotting README files and rewrite the README to point
readers toward authoritative sources of documentation.
---
README | 100 +++----------------------
README.cdn-X | 73 ------------------
README.configure | 222 ------------------------------------------------------
3 files changed, 11 insertions(+), 384 deletions(-)
delete mode 100644 README.cdn-X
delete mode 100644 README.configure
diff --git a/README b/README
index 37aeed9..2c7c661 100644
--- a/README
+++ b/README
@@ -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.
diff --git a/README.cdn-X b/README.cdn-X
deleted file mode 100644
index d259d5d..0000000
--- a/README.cdn-X
+++ /dev/null
@@ -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.
diff --git a/README.configure b/README.configure
deleted file mode 100644
index 6ca355e..0000000
--- a/README.configure
+++ /dev/null
@@ -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.
--
1.7.1
More information about the devel
mailing list