xBGAS-RUNTIME
contact@tactcomplabs.com
--------------------------------------------------------------------------------

xBGAS Machine Runtime Library

--------------------------------------------------------------------------------

I.  Intro
--------------------------------------------------------------------------------

The xBGAS machine runtime library is designed to provide OpenSHMEM-like
functionality for an xBGAS-enabled RISC-V system architecture.  The xBGAS
machine runtime library is written in a mixture of C and Assembly in order to
provide high performance SHMEM "Get" and "Put" functionality for other libraries
and users.

II. Requirements
--------------------------------------------------------------------------------

The xBGAS runtime library requires the following packages to build:
- xBGAS RISC-V Tools: https://github.com/tactcomplabs/xbgas-tools
- CMake 2.6+

The xBGAS tools should be installed to a directory pointed to by the
$RISCV environment variable (per the core RISCV tools build directions)

III.  Compiling
--------------------------------------------------------------------------------

Compiling the xBGAS runtime requires that the user set the $RISCV environment
variable to point to the appropriately installed xBGAS tools.  Building
the library can be performed as follows:

$> git clone https://github.com/tactcomplabs/xbgas-runtime.git
$> cd xbgas-runtime
$> mkdir build
$> cd build
$> cmake ../
$> make

...will create ~/xbgas-runtime/build/src/xbgas-runtime/libxbrtime.a

Additional build arguments for CMake are as follows:
- -DCMAKE_BUILD_TYPE=Debug : enables debug builds with debug symbols
- -DCMAKE_BUILD_TYPE=Release : enables release builds with full optimization (default)
- -DBUILD_DOCUMENTATION=ON : enables documentation; requires Doxygen; "make doc"

IV.   Installing
--------------------------------------------------------------------------------

First, follow the steps in Section III. to compile the source code and
the documentation.  Additionally, you can specify the following cmake directive
to change the installation location:

- -DCMAKE_INSTALL_PREFIX=/path/to/installation/

Once you have compiled the library and the documentation, do the following
to install the library, headers and docs:
$> make install

V.    Testing
--------------------------------------------------------------------------------

The test harness for the xBGAS runtime library is built into the CMake build
infrastructure.  If you would like to build and run the integrated xBGAS
tests, add the following to your cmake build configuration:

- -DBUILD_ALL_TESTING=ON

If you would like to enable individual blocks of tests, you can do so via
the following cmake build arguments:

- -DBUILD_INIT_TESTING=ON   : enables the "init" tests
- -DBUILD_ALLOC_TESTING=ON  : enables the allocation/free tests
- -DBUILD_XFER_TESTING=ON   : enables the data transfer tests

Once you have build the library and associated tests, you can run the tests
via the following command line:

$> make test

NOTE: All the tests require that the "$RISCV" environment variable be set
as was the case with the build process.  Also note that the "mpirun"
binary (utilized in building the xBGAS-tools) must also be in the standard
$PATH.  All the tests are currently set to run using two PE's.

VI.    Demo & Tutorials
--------------------------------------------------------------------------------
The following video introduces how to play with RISC-V xBGAS extension, including
programming with the xBGAS runtime, compiling, and executing the xBGAS benchmarks.

* https://youtu.be/IeIpJkMjMuc

--------------------------------------------------------------------------------
EOF