Distributed-Run-Time-Resource-Manager/RCCE_V2.0

//
// Copyright 2010 Intel Corporation
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
//

Welcome to RCCE, a communication environment for the SCC processor
------------------------------------------------------------------

RCCE is designed to run on a variety of platforms including:

* Baremetal on the SCC chip,
* Linux on the SCC chip,
* A functional emulator running on top of OpenMP.

============ test line ============
This particular release has been validated only for Linux and the
OpenMP emulator (a baremetal build option is available, but has
not been tested). It may seem a bit cumbersome to work with, but
that's so we can replicate the "features" of the SCC chip ... i.e.
once a program runs on the emulator, it's likely to work on real
hardware.

There are several versions of the RCCE library that can be
built with this release. They expose different options ...

* The "gory" interface ... this is the low level interface. It
makes the programmer responsible for declaring and managing
synchronization flags and for managing the on-chip message
passing buffer. This mode gives access to the low level
get/put routines, as well as to the higher level two-sided
send/receive interface.

* The "nongory" interface ... a higher level interface that
hides the particulars of the message passing buffers and
inter-core synchronization from the programmer, including the
management of synchronization flags. This interface does not
give access to the low level put/get routines.

* Big Flags ... each flag used to coordinate interaction
between units of execution (UE) takes up a byte in a single cacheline.
This has lower latency but wastes memory.

* Small flags ... flags are stored in a single bit; many are
packed into a single cache line. A slight hit on latency but
consumes less message passing buffer memory.

* With or without software controlled power management. POWER
MANAGEMENT IS AN EXPERIMENTAL FEATURE THAT HAS NOT BEEN TESTED
AS THOROUGHLY AS THE REST OF THE LIBRARY. FOLLOW THE SPECIAL
INSTRUCTIONS BELOW TO CONFIGURE THE "makeall" SCRIPT TO BUILD
VERSIONS OF THE LIBRARY THAT INCLUDE THE POWER MANAGEMENT API.


You can build all versions of the library supported with this
release, as follows:

1. Type "./configure ". This creates file common/symbols
from file common/symbols.in, inserting the proper root of the
directory tree, and also inserting the proper platform (SCC_LINUX,
SCC_BAREMETAL, or emulator). Any existing file common/symbols
will be overwritten, so do not update that file by hand. Instead,
specify details of your build environment in common/symbols.in
The configure utility also specializes the rccerun command (see
below) for the target platform. You may need to make the configure
script executable (type "chmod u+x configure").
To enable RCCE's power management API, you must specify the string
"ADD_POWER_API" as the second parameter on the command line when
you execute the configure script. Because this is an experimental
feature, it is not built by default. See above.

2. Type "./makeall" to build all libraries. Alternatively you
can build individual libraries by calling make directly.
Type "make usage" to discover the libraries you can build.

The libraries generated by this procedure will be put in the directory

bin/

An easy way to test correct operation of the platform is to build and
run a prepackaged RCCE stress test after building the RCCE library:
"./build_stress_test; ./run_stress_test "
where size is -S (small), -M (medium), or -L (large).

A number of applications are included with this release in the
"apps" directory. These include:

* PINGPONG: bounces messages between a pair of UEs
* SHIFT: passes messages around a logical ring of UEs
* STENCIL: solves a simple PDE with a basic stencil code
* SHARE: tests the off-chip shared memory access
* NPB: NAS Parallel Benchmarks, LU and BT
* XHPL: the Linpack benchmark

To build an application, go to the corresponding subdirectory of "apps"
and type "make". It will return a list of options for building
versions of an application. It may be necessary to edit the Makefile
in an application directory if parts of the original RCCE code tree
got moved with respect to each other.

We suggest that you start with PINGPONG, SHIFT, SHARE, and STENCIL and
save the more complex NPB and XHPL for later. The STENCIl directory
contains a few simple variations of the base code that exercise RCCE's
experimental power management API.
See the apps/XHPL directory for instructions on how to build and run
Linpack.

To run an application, you must use the rccerun command. This command
is used to launch Linux jobs on SCC or on the emulator. To run application
APP with P cores, type

"rccerun -nue P -f HOSTFILE APP [application parameters]"

where HOSTFILE contains the list of physical core IDs to be used.
By default, the host file "./hosts/rc.hosts" should be used.
You can see an example of the use of rccerun in the run_stencil and
run_stencil_synch shell scripts in the "apps/STENCIL" directory.

If my_script is a shell script that contains the actual RCCE executable
RCCE_X (which may take application parameters), make sure to execute it as
follows inside the script: "/path_to_RCCE_X/RCCE_X $@" This is necessary
so that all the parameters to the program, including those added by
rccerun, are supplied to the executable.

Example:
Shell script my_script contains executable RCCE_X that expects two
parameters, n and m. Write the script as:
----------start of my_script---------
line 1
line 2
line ...
./RCCE_X $@
line ...
----------end of my_script-----------
To run the code on P cores of the SCC, type

"rccerun -nue P -f HOSTFILE my_script m n"

MANPAGES
This release of RCCE has manpages. To access those manpages, add a path to
your MANPATH as follows:
export MANPATH="/man:${MANPATH}"