// 
// 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) fills a whole cache line.  
     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 <PLATFORM>". 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/<PLATFORM>

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 <size>"
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="<path to where you installed RCCE>/man:${MANPATH}"