From 0ced77e947aa09944723c3e4f6312a42446bd3a9 Mon Sep 17 00:00:00 2001 From: Gedare Bloom Date: Mon, 22 Apr 2013 13:14:36 -0400 Subject: README: Rewrite and reduce 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 37aeed9933..2c7c66117f 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 d259d5d4b2..0000000000 --- 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 -/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 -/rtems/configure [options] \ ---target=sparc-rtems \ ---build=`/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 /make/ directory hierarchy is not treated correctly. diff --git a/README.configure b/README.configure deleted file mode 100644 index 6ca355e3b1..0000000000 --- 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. -- cgit v1.2.3