rtems-patmos/readme.txt

=======================
Installing RTEMS 4.10.2
=======================

In this installation guide we present the steps to install RTEMS 4.10.2 for the
Patmos Pasim BSP. Additionally, for testing/comparison purposes, we present the
same install process for the SPARC Leon3 BSP.
Currently, both the Leon3 BSP and the Pasim BSP are completely functional.

Documentation on RTEMS can be found on:
http://www.rtems.org/onlinedocs/releases/
Documentation on version 4.10.2 of RTEMS can be found on:
http://www.rtems.org/onlinedocs/releases/rtemsdocs-4.10.2/share/rtems/html/

As an alternative to this manual installation process, the 'build.sh' script in
the T-CREST misc repository automatically goes through all the steps required
to install RTEMS 4.10.2 for Patmos. To do so, run the script as follows:

'./build.sh rtems'

Similarly, the 'build-rtems.sh' script contained in this repository also
enables the automatic installation of both the patmos toolchain and rtems.
To do so, clone this repo and then run the script as follows:

'./build-rtems.sh -m -t -r'

This will automatically create a 't-crest' folder with 3 subfolders:

(a) 'patmos-misc' with the contents of the t-crest misc repo

(b) 'build-rtems' with the installation of the patmos toolchain for rtems

(c) 'rtems' with the 'rtems-src', 'rtems-build' and 'rtems-install' locations




==================================
Installing RTEMS 4.10.2 for Patmos
==================================

Installing the Patmos compiler
==============================

In order to compile RTEMS 4.10.2 OS for Patmos, we need to install the
Patmos compiler tool chain in a slightly different manner than the usual. 
Assuming that we are using the Build Script to build the Tool Chain:

(a) Download/Checkout the build script: 
'git  clone  https://github.com/t-crest/patmos-misc.git  <misc_dir>'

(b) 'cd  <misc_dir>'

(c) 'cp  build.cfg.dist  build.cfg', then edit build.cfg to:
	(c.1) set ROOT_DIR
	(c.2) change TARGET="patmos-unknown-unknown-elf" to 
		  TARGET="patmos-unknown-rtems"
	(c.3) uncomment GOLD_CXXFLAGS="-Wno-narrowing"
	
The RTEMS build system requires compiler, assembler and linker tools to be 
compliant with the target of the installation (CPU-Vendor-OS). Therefore, 
the Patmos executables created in this installation must be renamed, copied or 
symbolically linked under different names. E.g. the patmos-clang compiler tool
will have to be renamed to patmos-unknown-rtems-clang:

'ln -s patmos-clang patmos-unknown-rtems-clang'

In this folder there is a script named 'build-rtems.sh' that installs the
Patmos toolchain as required by RTEMS, including renaming the Patmos binary 
files. Thus, running './build-rtems.sh -m' will check out the misc repo and
then run the build.sh script with the required configurations for rtems.
The file 'target-change.sh' is responsible for renaming the Patmos tools,
hence needs to be placed in the same directory as the 'build-rtems.sh' script.
Alternatively, and assuming that the Patmos toolchain is already installed, the
'target-change.sh' script can be used alone to copy the Patmos tools,
e.g. like this: './target-change.sh ROOT_DIR'.

Finally, the Patmos executables must be added to the path environment variable
(e.g. 'export PATH=${PATH}:/ROOT_DIR/local/bin').
Similarly, the pasim simulator must also be added to the path environment
variable (e.g. 'export PATH=${PATH}:/ROOT_DIR/patmos/simulator/build/src').
The 'build-rtems.sh' script also adds these paths to the path env variable, and
in addition it adds these exports to the bashrc file.


Installing RTEMS 4.10.2
=======================

Use the command 'git clone https://github.com/t-crest/rtems <rtems_src_dir>' to 
download the build files of RTEMS 4.10.2. Prior to the installation process, it
is necessary to run the bootstrap script. The bootstrap script found in the 
top level directory of the RTEMS source tree is executed to produce the 
automatically generated files. The bootstrap command is usually invoked in one
of the following manners:

(a) bootstrap to regenerate all files that are generated by
	autoconf and automake.

(b) bootstrap -c to remove all files generated by autoconf and automake.

(c) bootstrap -p to regenerate preinstall.am files.

After cloning the RTEMS repository, the bootstrap script should be run in the
following manner:

 (a) ./bootstrap -p
 
 (b) ./bootstrap

Once RTEMS 4.10.2 is bootstraped, the configure script should run. The
configure process specializes the Makefile.in files at the time that RTEMS is 
configured for a specific development host and target.

Configure for Patmos Pasim
--------------------------

Prior to configuring RTEMS with the Pasim BSP, create and go to the
configuration directory:

'mkdir <rtems_build_dir>'
'cd <rtems_build_dir>'

To configure RTEMS using the Patmos Pasim BSP, use the following command:

'<rtems_src_dir>/configure --target=patmos-unknown-rtems --enable-posix 
--disable-networking --disable-cxx --enable-rtemsbsp=pasim --prefix=<rtems_install_dir>'

It is assumed that the source files for the installation are placed at
<rtems_src_dir> directory, and the variable <rtems_install_dir> should be
replaced by the installation directory (e.g. '~/t-crest/rtems/rtems-install').
The script shoud be executed from the configuration directory
(e.g. '~/t-crest/rtems/rtems-build').

The options passed to the configure script will determine which tools RTEMS
will include in the installation. In this case, the '--enable-posix' option
specifies that the POSIX API (profile 52) will be available in this
installation. Moreover, networking was disabled because the current version of
Patmos does not have an Ethernet interface. As for the '--disable-cxx' option,
since typical avionics applications do not rely on C++, there is no need to
enable it in RTEMS. An additional '--enable-tests' option can be added to this
script to instruct RTEMS to compile its testsuite.

Finish installation
-------------------

After configuring RTEMS for the specific CPU and board target, use
'make install' to install RTEMS 4.10.2. Next, set the path to the RTEMS
specific installation. Assuming '<rtems_install_dir>=~/t-crest/rtems/rtems-install':

'export RTEMS_MAKEFILE_PATH=~/t-crest/rtems/rtems-install/patmos-unknown-rtems/pasim'

Test installation
-----------------

To test installation, to check if the OS is working properly, 
checkout the RTEMS Classic API examples at Github, using 
'git clone https://github.com/RTEMS/examples-v2 <rtems_examples_dir>'. 
Assuming '<rtems_examples_dir>=~/t-crest/rtems/rtems-examples':

(a) go to the triple period example, using 
	'cd ~/t-crest/rtems/rtems-examples/classic_api/triple_period'

(b) use 'make' to create the executable

(c) run the executable, using 'pasim o-optimize/triple_period.exe'

In case RTEMS was configured with tests enabled, the testsuite was compiled
in the configuration directory. Then:

(a) go to the testsuite folder in the configuration drectory, using
	'cd <rtems_build_dir>/patmos-unknown-rtems/c/pasim/testsuites'
 
(b) go through all the test folders and execute each test individually e.g.
	'cd sptests/sp01'
	'pasim o-optimize/sp01.exe'
	 
(c) compare the output of the test with the expected successful output
	contained in the .scn files located in the RTEMS source tree (e.g.
	'<rtems_src_dir>/testsuites/sptests/sp01/sp01.scn') to check if the
	test passed
	 
Alternatively, the 'build.sh' script in the T-CREST misc repository includes
the '-t' option that runs the complete RTEMS testsuite for Patmos and checks
its results. The 'run-testsuite.sh' script present in this repository also
performs these functions. The script should be executed from this source dir.
Run './run-testsuite.sh -h' to check the script options.

	

	
	
	
=================================
Installing RTEMS 4.10.2 for SPARC
=================================
	
Installing SPARC-RTEMS4.10 tools
================================

To install sparc-rtems4.10 tools, go to
http://www.rtems.org/ftp/pub/rtems/linux/4.10/ and download the appropriate
files. E.g. for the Fedora distribution of Linux, go to
http://www.rtems.org/ftp/pub/rtems/linux/4.10/fedora/17/x86_64/, and download:

(a) rtems-4.10-release-0.20130314.0-1.fc17.noarch.rpm
(b) rtems-4.10-yum-conf-0.20130314.0-1.fc17.noarch.rpm

Next, execute the following commands:

'sudo rpm -ivh rtems-4.10-release-0.20130314.0-1.fc17.noarch.rpm'
'sudo rpm -ivh rtems-4.10-yum-conf-0.20130314.0-1.fc17.noarch.rpm'
'sudo yum install rtems-4.10-sparc-rtems4.10-*'


Installing Leon3 Simulator
==========================

To install the Leon3 simulator, go to
http://www.gaisler.com/index.php/downloads/simulators?task=view&id=157, and
download file 'tsim-leon3-2.0.24.tar.gz'. Then, just use command
'tar tsim-leon3-2.0.24.tar.gz' to untar the file, and run 
'export PATH=$PATH:/opt/rtems-4.10/bin' to make the tsim-leon3 simulator
available for use.

Installing RTEMS 4.10.2
=======================

Use the command 'git clone https://github.com/t-crest/rtems <rtems_src_dir>' to 
download the build files of RTEMS 4.10.2. Prior to the installation process, it
is necessary to run the bootstrap script. The bootstrap script found in the 
top level directory of the RTEMS source tree is executed to produce the 
automatically generated files. The bootstrap command is usually invoked in one
of the following manners:

(a) bootstrap to regenerate all files that are generated by
	autoconf and automake.

(b) bootstrap -c to remove all files generated by autoconf and automake.

(c) bootstrap -p to regenerate preinstall.am files.

After cloning the RTEMS repository, the bootstrap script should be run in the
following manner:

 (a) ./bootstrap -p
 
 (b) ./bootstrap

Once RTEMS 4.10.2 is bootstraped, the configure script should run. The
configure process specializes the Makefile.in files at the time that RTEMS is 
configured for a specific development host and target.

Configure for SPARC Leon3
-------------------------

Prior to configuring RTEMS with the Leon3 BSP, create and go to the
configuration directory:

'mkdir <rtems_build_dir>'
'cd <rtems_build_dir>'

To configure RTEMS using the SPARC Leon3 BSP, use the following command:

'<rtems_src_dir>/configure --target=sparc-rtems4.10 --enable-posix
--disable-networking --disable-cxx --enable-rtemsbsp=leon3 --prefix=<rtems_install_dir>'

It is assumed that the source files for the installation are placed at
<rtems_src_dir> directory, and the variable <rtems_install_dir> should be replaced by
the installation directory (e.g. '~/t-crest/rtems/rtems-install'). The script shoud be
executed from the configuration directory (e.g. '~/t-crest/rtems/rtems-build').

The options passed to the configure script will determine which tools RTEMS
will include in the installation. In this case, the '--enable-posix' option
specifies that the POSIX API (profile 52) will be available in this
installation. As for the '--disable-cxx' option, since typical avionics
applications do not rely on C++, there is no need to enable it in RTEMS. An 
additional '--enable-tests' option can be added to this script to instruct
RTEMS to compile its testsuite.

Finish installation
-------------------

After configuring RTEMS for the specific CPU and board target, use
'make install' to install RTEMS 4.10.2. Next, set the path to the RTEMS
specific installation. 
Assuming '<rtems_install_dir>=~/t-crest/rtems/rtems-install':

'export RTEMS_MAKEFILE_PATH=~/t-crest/rtems/rtems-install/sparc-rtems4.10/leon3'

Test installation
-----------------

To test installation, to check if the OS is working properly, 
checkout the RTEMS Classic API examples at Github, using 
'git clone https://github.com/RTEMS/examples-v2 <rtems_examples_dir>'. 
Assuming '<rtems_examples_dir>=~/t-crest/rtems/rtems-examples':

(a) go to the triple period example, using 
	'cd ~/t-crest/rtems/rtems-examples/classic_api/triple_period'

(b) use 'make' to create the executable

(c) run the executable, using 'tsim-leon3 o-optimize/triple_period.exe'

In case RTEMS was configured with tests enabled, the testsuite was compiled
in the configuration directory. Then:

(a) go to the testsuite folder in the configuration drectory, using
	'cd <rtems_build_dir>/sparc-rtems4.10/c/leon3/testsuites'
 
(b) go through all the test folders and execute each test individually e.g.
	'cd sptests/sp01'
	'tsim-leon3 o-optimize/sp01.exe'
	 
(c) compare the output of the test with the expected successful output
	contained in the .scn files located in the RTEMS source tree (e.g.
	'<rtems_src_dir>/testsuites/sptests/sp01/sp01.scn') to check if the
	test passed